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PREFACE 


Who needs to use this manual? 


The DGL Programner Reference hkxnual is intended for users of 
Hewlett-Packard's Device-independent Graphics Library (DGL). Application 
prograunmers can use it to learn the features of DGL as well as for reference 
material as they write their application programs. Operators of graphics 
systems may better understand the system they use by reading the first two 
chapters of this manual. 


What does it cover? 


This manual teaches the DGL system and contains reference information for 
DGL. Designers and programmers will also find the Device Handlers Manual 
helpful. This manual explains the effect that certain DGL routines have on 
different devices. This manual does not contain reference information for 
DGL calls that are operating system dependent. Refer to the particular sys¬ 
tem supplement manual for this information. 


What does it assume? 


Very little is assumed by the DGL Programner Reference Manual, An overall 
understanding of basic concepts of computers (e.g. programs, peripherals) 
is needed. Some familiarity with computer graphics is helpful. A thorough 
reading and understanding of Chapter 1 can provide this. Also, knowledge 
of the FORTRAN programming language is desirable, since that is the language 
in which examples are written. Experience with additional languages, such 
as Pascal, would complement the FORTRAN knowledge and allow those languages 
to be used for graphics application production. 


How is it organized? 

This manual can be divided into two sections: a "user's guide" and a 
"reference manual". The "user's guide", consisting of the first two chap¬ 
ters, teaches the basic concepts of computer graphics and the functions of 
the DGL system. This should be read by the first time user in order to gain 
a general understanding of the DGL package. The third chapter comprises the 
"reference manual". This chapter discusses information needed by every 
programmer as well as more experienced DGL users. 
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Chapter 1 

Concepts of Computer Graphics 


INTRODUCTION 


The Device-independent Graphics Library (DGL)^ is a set of graphics tools 
that allows an application programmer to interact with aind perform 
graphics output to a variety of graphics display devices. A user can send 
two types of output and receive four types of input from several devices. 

To provide a device-independent interface, the DGL system is centered 
around the concepts of a logical device and a work station. A logical 
device is a hypothetical device which can perform some type of input or out¬ 
put to different physical devices in a uniform manner. DGL has 6 different 
types of logical devices: 

OUTPUT INPUT 

Graphics display Button 

Alphanumeric display Keyboard 

Locator 

Valuator 


DGL combines these logical devices into a "super device" called a 
work station. A work station is a group of, at most, one each of the six 
logical devices that DGL treats as a unit. It allows a single application 
program to send different types of output and receive different t 3 rpes of in¬ 
put from several devices. Figure 1-1 illustrates the structure of the DGL 
system. 

DGL is a set of building blocks upon which prograonmers can build a wide 
variety of graphics tasks (which requires a minimal amount of program space) 
without sacrificing performance. DGL is an extremely flexible product which 
can be extended to support new peripherals as they become available. 

The following sections describe the five major functional areas of DGL: 
graphics output primitives, output primitive attributes, viewing transforma¬ 
tions, input, and control. The concepts and examples introduced here will 
be developed in detail in the following chapters. 


1-1 




DGL RO 

UTINES 










► 

DEVICE 

DEVICE 

DEVICE 

DEVICE 

DEVICE 

DEVICE 

DEVICE 


HANDLER 

HANDLER 

HANDLER 

HANDLER 

HANDLER 

HANDLER 

HANDLER 












> DGL 




i i 

i i 

r 

i 

r 1 

r ^ 

I/O C 




SYSTEM DRIVERS 





k k k k k k 


DISPLAY 

DEVICE 


ALPHA¬ 

NUMERIC 

DEVICE 


LOCATOR 




KEYBOARD 

DEVICE 


DEVICE 


BUTTON 

DEVICE 


VALUATOR 

DEVICE 


Figure 1-1. DGL System Structure 
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GRAPHICS OUTPUT PRIMITIVES 


Graphics output primitives are the building blocks of a graphics picture. 
Just as an algorithm is broken into the simplest possible instructions to 
create a computer program, a picture can be broken down into graphics output 
primitives. DGL has six types of graphics primitives: lines, polylines, 
text, markers, polygon sets, and moves. 

o A line is a single line segment. 

o A polyline is a a series of connected lines specified as one primi¬ 
tive. Note that the polyline primitive can define the outline of a 
polygon but not its interior region. The polyline primitive makes 
it possible to draw a series of connected lines all at one time, in¬ 
stead of making a series of draws. This is done by specifying the 
number of points to be drawn and the X and Y arrays of the coor¬ 
dinates to be connected. 

o Text is a string of graphics text characters which is output. The 
lower left comer of the first text character begins at the starting 
position. Text is normally output by the device's hardware charac¬ 
ter generator. For devices that do not generate graphics text, DGL 
will output software-generated text. 


o A marker is a symbol, such as a diamond or star, that represents a 
data point. 

o A polygon is a multisided, closed, plane figure that includes both 
the edge or sides of the figure and the region enclosed by the edge. 
A polygon set is a group of associated polygons each of which is a 
closed plane figure bounded by straight lines. The polygon set 
primitive allows the user to draw a series of connected lines to 
form closed figures (polygons) in the world coordinate system. Like 
polylines, the user specifies the number points to be drawn and the 
X and Y arrays to be connected. Unlike polylines, the polygon set 
primitive is planar and allows the user to specify how the interior 
of these bounded regions is to be filled with a specific style and 
color of fill pattern. 

o A move redefines the starting position for the next graphics primi¬ 
tive. Otherwise, each primitive begins where the previous primitive 
ended. 


In Figure 1--2, moves and lines were used to create the axes aind grid, 
markers generated the data points, and polylines connected the data points. 
The move primitive positioned the labels on the axes, and the text primitive 
wrote the labels. 
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Figure 1-2. Examples of Graphics Output Primitives 


The location of each output primitive is specified in the world coordinate 
system. The world coordinate system is an abstract, two-dimensional space 
expressed in units selected by the user. 

A point is defined by its X and Y coordinates. The starting point of an 
output primitive is the ending point of the previous output primitive. A 
line cam be created by specifying a point to be connected to the previous 
point. This action is known as a "draw". The end of that line then becomes 
the starting point of the next output primitive and another line cam begin 
at those coordinates. The starting position can also be moved to another 
point without drawing a line; this is known as a "move". In this way, a 
picture can be drawn by successive moves and draws. 

Using lines, polylines, text, markers, polygon sets, and moves, complex 
graphics images can be constructed as shown in Figure 1-3• 
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Figure 1-3. Examples of Graphic Output Using DGL 


PRIMITIVE ATTRIBUTES 


Primitive attributes are the visual characteristics of graphics primitives. 
For example, a line has the attributes of color, highlighting, linewidth, 
and linestyle. Different values of the linestyle attribute give a line the 
different appearances shown in Figure 1-4. 
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Figure 1-4. A Primitive Attribute: Linestyle 


For most CRTs and all graphics plotters, primitive attributes are fixed when 
they are output; they cannot be changed retroactively. To change the image 
of an output primitive, clear the display, change the desired attribute 
values, and display the primitive again. 


VIEWING TRANSFORMATIONS 


As objects are created, they are trajnsformed for viewing. A 
viewing transformation is the method whereby an object, a collection of 
graphics primitives defined in soi abstract coordinate system, is converted 
to an image displayed on a physical graphics display device. The bounds of 
the system in which an object is defined and the location of the object's 
image on the display device can be defined by the user. 

DGL's viewing transformations are all in two dimensions. To define the two- 
dimensional viewing transformation, three questions must be addressed: 




1. What portion of the world coordinate system will be used to define 
and display the object (where is the Wind(M)‘l 

2. Where will the window be mapped in the virtual coordinate system 
(where is the viettport)? 

3. Where will the virtual coordinate system be placed (what are the 
logical display limits)! 

Setting the window allows the application to specify which portion of the 
world coordinate space is to be used. This provides the application program 
with the flexibility of working in units that are relevant to the applica¬ 
tion. Since the window is in the same coordinate space in pdiich objects are 
defined, the bovinds of the window can affect the size of the image dis¬ 
played. The larger the limits of the window, the smaller the object's im¬ 
age. If the window is specified as having smaller limits than the object, 
vinpredictable device-dependent results will occur, since the DGL system does 
not perform software clipping. Figure 1-5 shows the effect of two different 
windows on the same object. The window on the left shows a window which is 
approximately as large as the object contained within it. The window on the 
right shows the same object in a larger window. 



Figure 1-5. Two Images Resulting From Different Windows 
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The area on a display device where images appear is called a viewport. The 
dimensions of the viewport are set in the virtual coordinate system, which 
is the two-dimensional system whose units range from 0.0 to a maximum of 
1.0. The viewport cam map to any area on the surface of the graphics dis¬ 
play device. Multiple viewports can be defined sequentially so that several 
images can be displayed together. Figure 1-6 shows such an example. 



Once the window and viewport have been defined, output primitives within the 
window are mapped into the viewport so that each point in the window cor¬ 
responds to a point in the viewport. If the aspect ratio (height-to-width 
ratio) of the window and viewport are not equal, this mapping will distort 
(shrink or stretch) the image. This is the only stage of the transformation 
process where distortion can occur. 

To offer full flexibility in accessing display devices of different sizes 
and shapes, DGL lets the application program control the mapping of the vir¬ 
tual coordinate system to the display surface. The logical display limits 
can be defined to alter the absolute size of the image that is produced. 
These limits bovtnd the logical display surface, making it the entire display 
surface or some subset of it.. The adjective "logical" distinguishes this 
surface from the true surface of the display device itself, sometimes called 
the physical display surface. 

The steps in the mapping of objects in the window to images on a logical 
display surface are somewhat complex. They are described more fully in 
Chapter 2, where the DGL routines that control this mapping are presented. 
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INPUT 


Input functions return information to an application prograim from input 
devices. There are four available devices: button, keyboard, locator, and 
valuator. 

A button device returns an integer value corresponding to a button selected. 
Button devices are used for applications that require only simple choices by 
the operator (rather than complex strings of characters such as those en¬ 
tered with a keyboard). A button device is analogous to a start/stop/select 
device, such as a button on a slide projector. 

A keyboard device allows the operator to enter a string of characters, typi¬ 
cally from an alphanumeric keyboard. The keyboard function returns the 
string that was entered and the number of characters in the string to the 
calling program. This device is useful for complex responses by operators. 

A locator device provides a means of inputting a real coordinate pair that 
depicts a point on the view surface. Typical locator devices are graphics 
tablets and the graphics cursor on a terminal. Using a locator is analogous 
to using one's finger: With a finger, one catn point to the location of a 
city on a map thereby determining its latitude and longitude. 

A valuator device allows the operator to return a value between 0.0 and 1.0 
to the application program. The device caui be a control dial or multiposi¬ 
tion switch, analogous to a dimmer switch on a light. The dimmer can be 
rotated to any position, which sets the light at the desired intensity. 

DGL obtains information from the input devices by either requesting or sam¬ 
pling the input. Before requested information can be returned to the ap¬ 
plication program, the operator must enter a termination command (such as 
pressing the return key). Sampled output is returned to the application 
program immediately, with no operator interaction required. Information 
from all logical input devices can be obtained by the request method. Only 
the locator and valuator devices may be sampled. 


CONTROL 


Control functions are used to manage various aspects of a graphics applica¬ 
tion. Some of these are initialization and modification of the graphics en¬ 
vironment, inquiry of the features currently in effect, and escape 
functions. 
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ALPHANUMERIC OUTPUT 


DGL supports a mechanism that allows the application program to send non¬ 
graphics text and data to an alphanumeric display device. This call can be 
used to send prompts, give status, or print other messages. To maintain the 
integrity of communications between the DGL system and the devices accessed, 
this mechanism, rather than I/O mechanisms of other subsystems, should be 
used to generate alphanumeric output on DGL devices. 
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Chapter 2 
Description of DGL Functions 

GENERAL 


IXjL is a set of graphics tools that allows the application programmer to in¬ 
teract with and send output to a wide variety of graphics devices. A user 
can send two types of output and receive four types of input in a uniform 
manner from several devices. This chapter describes the functions of DGL. 
Detailed descriptions of DGL routines are given in Chapter 3. 

An application program cam perform two types of output: graphics amd al¬ 
phanumeric. Graphics output creates elements of a graphics object. An ob¬ 
ject may consist of line segments, polylines, markers, text, polygon sets 
amd moves. The appearance of the graphics output cam be controlled by vary¬ 
ing the values of the primitive attributes: color, highlighting, linestyle, 
linewidth, and character size. 

Alphanumeric output cam be used to send operator prompts and messages. It 
is composed entirely of alphanumeric text and is not affected by the primi¬ 
tive attributes. 

DGL transforms objects that are expressed in terms of am abstract two- 
dimensional space into visible images on a physical graphics device, by 
means of a viewing transformation (see Figure 2-1). 
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OBJECT 


Figure 2-1. The Result of the Viewing Transformation 


To provide a device-independent interface, the DGL system is centered around 
the concepts of a logical device and a work station. A logical device is a 
hypothetical device which can perform a certain type of input or output in a 
uniform manner independent of the physical device. For example, a logical 
locator always returns an (X,Y) coordinate regardless of whether the physi¬ 
cal device is an HP 9 III Data Tablet or an HP 2623 Graphics Terminal. 
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DGL has six different types of logical devices: 


OUTPUT 

Graphics display 
Alphanvuneric display 

INPUT 

Button - returns an integer 
Keyboard - returns alphanumeric text 
Locator - returns aui (X,Y) point 

Valuator - returns a real value between 0.0 and 1.0 


Several logical devices can be combined to form a work station. A 
work station is a collection of logical devices and can be thought of as a 
"super" logical device. It can be composed of any or all of the logical 
device types but cannot contain more than one of any type. For example, it 
is not possible to have an HP 2623 locator and an HP 9111 locator in the 
same work station. One work station caui input data points from a locator on 
a graphics tablet, input a text string from a keyboard on a terminal, aind 
display the data points on a CRT display. 

An application program may also control when visual chauiges occur on the 
graphics display. Graphics commands ceui either be sent immediately to a 
device or can be placed in an internal DGL buffer before being transmitted. 
The mode used affects the efficiency of the DGL system and the immediacy of 
visual changes. 

The DGL system allows an application program to inquire the status of the 
system at any time after the program initializes the system. 

In summary, DGL can perform mainy graphics tasks. This chapter gives a 
description of each of the DGL functions as well as how to use them. 
Example programs and their output illustrate h6w one can use these fvmctions 
to easily create graphics application programs. 
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OUTPUT 


General Information 


This section discusses the two types of DGL output. The elements of 
graphics output auid how they can be used to create objects are presented 
first. The method of sending alphanumeric messages is explained at the end 
of the section. 


Graphics Output Primitives 

GENERAL 


Graphics output primitives are used to define an object in terms of the 
world coordinate system. This is an abstract two-dimensional space ex¬ 
pressed in xinits defined by the user. The programmer c 2 Ln define an object 
in familiar units, such as kilometers, seconds, or greuns. 

Graphics output primitives are interpreted as commands to generate lines, 
markers, polygon sets, and graphics text at specified locations on the 
graphics display device. Each primitive begins at the position where the 
previous primitive ended. This means that the starting position of a primi¬ 
tive is not explicitly specified, but rather implied by the previous output 
primitive. For example, a marker is always output centered about the start¬ 
ing position. 


STARTING POSITION 


ZMOVE (WX, WY) Define a starting position 

The subroutine ZMOVE allows the user to specify a new starting position. A 
call to this subroutine causes the next output primitive to start at the 
coordinate point (WX,V7Y). This point will then be the endpoint of a line 
segment, the left edge of a graphics text string, or the point that a marker 
is centered around. 
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LINES 


ZDRAW (WX, WY) Draw a line to point (WX,WY) 
ZPOLY (NPTS, XVEC, YVEC) Draw a connected line sequence 

Line output primitives are used to draw graphics objects. A call to ZDRAW 
causes a line to be drawn from the starting position to the world coordinate 
point specified by (WX,WY). The starting position then becomes (WX,WY). 

DGL also provides the capability to draw a series of connected lines by 
making one call to the subroutine ZPOLY. This call first does a move to the 
point specified by the first element of the arrays XVEC and YVEC, where XVEC 
and YVEC contain a series of (X,Y) coordinate points. The line sequence 
begins at this point and is drawn to the second specified point, then to the 
third and continues until NPTS-1 lines are drawn. The starting position for 
the next primitive becomes the point specified by XVEC(NPTS) and YVEC(NPTS). 

The primitive attributes of color, highlighting, linestyle, and linewidth 
affect the appearance of lines. Primitive attributes are discussed later in 
this chapter. Figure 2-2 illustrates how a picture can be drawn using a 
combination of ZMOVE and ZDRAW commeuids or one call to ZPOLY. 


INTEGER NUMHOS, NUMTRE 

REAL XH0US(7), YH0US(7), XTREE(23), YTREE(23) 

DATA NUMH0S/7A NUMTRE/23/ 

DATA XHOUS/-.69,-.69,-.15,-.15,-.h2,-.69,-.15/ 

DATA YHOUS/-.38,-.85,-.85,-.38,-.08,-.38,-.38/ 

DATA xtree/.65,.65,.U6,.5U,.50,.58,.5**».62,.58,.65,.62, 

* . 69 ,.77,.73,.81,.77,.85,.81,.88,. 85 ,.92,.73,.73/ 
DATA YTREE/-.85,-.69,-.69,-.62,-.62,-.5l4,-.5^,-.l‘*6,-.U6,-.38, 

* -.38,-.31,-.38,-.38,-.lt6,-.U6,-.5U,-.5U,-.62,-.62, 

* -. 69 ,-. 69 ,-. 85 / 


C 

C Draw a house using a combination of ZMOVE & ZDRAW commauids 
C 

CALL ZMOVE(XHOUS(l), YHOUS(l)) 

DO 20 1=2, NUMHOS 

CALL ZDRAW(XHOUS(I),YHOUS(I)) 

20 CONTINUE 
C 

C Now draw the tree using one ZPOLY commauid 
C 

CALL ZPOLY (NUMTRE,XTREE,YTREE) 
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Figure 2-2. Use of ZMOVE, ZDRAW and ZPOLY 


TEXT 


ZTEXT (NCHARS, STRING) Generate graphics text 

DGL provides the ability to draw graphics text at a desired location on a 
graphics display device. Text is normally generated by a device's hardware 
character generator. DGL will simulate hardware text generation for any 
device that does not support a hardware character generator. 

A call to ZTEXT outputs the first NCHARS number of characters contained in 
the array STRING. The character string is drawn or displayed on the 
graphics display device beginning at the starting position. Text is normal¬ 
ly drawn from left to right and without character slant. The primitive at¬ 
tributes, color, linestyle, linewidth, highlighting, and character size af¬ 
fect graphics text. 

ZTEXT leaves the current position at a device-dependent location. After 
calling ZTEXT, define the starting position explicitly by calling 2310VE, 
ZPOLY, ZPGDD, or ZPGDI before generating more graphics primitives. 
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INTEGER TITLE(11) 

DATA TITLE/2H H,2H0M,2HE ,2H ,2HSW,2HEE, 
2HT ,2H ,2HH0,2HME,2H / 


C 

C Draw a house using a combination of ZMOVE & 

C ZDRAW commauids 
C 

CALL ZMOVE(XH0US(1),YH0US(1)) 

DO 20 I=2,NUMHOS 

CALL ZDRAW(XHOUS(I),YHOUS(I)) 

20 CONTINUE 
C 

C Now draw the tree using one ZPOLY command 
C 

CALL ZPOLY(NUMTRE,XTREE,YTREE) 

C 

C Write out the title, 'HOME SWEET HOME', using graphics text 
C 

CALL ZMOVE(XI,Yl) 

CALL ZTEXT(22,TITLE) 



Figure 2-3, Use of ZTEXT 
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MARKERS 


Z11ARK (MARKNO) Generate a marker 

Markers are used to identify individual points in the world coordinate sys¬ 
tem. Markers are center-oriented symbols which are output at the starting 
position. Depending on a particular display device's capabilities, DGL 
utilizes either software or hardware to generate the marker symbols. 

All graphics display devices support 19 standard marker symbols. The marker 
used is specified by the value of MARKNO. MARKNO is an integer in the range 
1-235' The 19 standard markers are defined as follows: 


Table 2-1. Standard Markers 


1 - . 

7 - rectangle 

13 - 3 

2 - + 

8 - diamond 

lU - k 

3 - * 

9 - rectangle 

15 - 5 

U - 0 

with cross 

16 - 6 

5 - X 

10-0 

17 - 7 

6 - triangle 

11-1 

18 - 8 


12-2 

19 - 9 


Besides these basic markers, each display device supports a device-dependent 
number of other markers that use any special marker symbols of that device 
(see the Device Handlers Manual). If the marker value specified is greater 
than the number of distinct markers supported by a device, then marker 1 
(".") is used. 

The orientation of a marker is centered around the starting position. The 
size of markers is device dependent and caumot be changed. The appearaince 
of markers is affected only by the color and highlighting attributes. The 
starting position is unchanged after a call to ZMARK. 
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POLYGONS 


ZPGDD (NPOINT,XVEC,YVEC,OPCODE) Draw a polygon set(device-dependent) 
ZPGDI (NPOINT,XVEC,YVEC,OPCODE) Draw a polygon set(device-independent) 

A polygon is a multisided, closed, plane figure. A polygon set includes one 
or more polygons, which may overlap. The DGL polygon routines draw the edge 
(the sides) of the polygon set, or the Interior region bounded by the edge, 
or both. 

A polygon set is defined in a single call to ZPGDD or ZPGDI and treated as a 
single polygon. The member polygons can intersect each other. The polygon 
set has one edge and one interior (see below) but either or both may be 
discontinuous. 

The edge of a polygon set is the set of edges of its member polygons. The 
edge of a member polygon is the set of edge segments, or sides of that 
polygon. Since member polygons may be totally \inconnected, the edge of a 
polygon set may be discontinuous. 

The interior of the polygon set is the region or regions enclosed by the 
edge an odd ntunber of times. A point which would be in the interior of a 
member polygon if it were considered by itself could be in the exterior of 
the polygon set. To decide whether a point is inside the set, draw a line 
(a ray) in any direction from that point. If the ray intersects the edge an 
odd nvimber of times, the point is inside the polygon set. If the ray inter¬ 
sects the edge an even number of times, the point is outside the set. 

This test is useful to see how DGL will fill the interior of a set consist¬ 
ing of concave, self-intersecting polygons, or multiple polygons. The test 
is also useful if member polygons overlap or enclose one another. Figure 
2-k shows several examples of polygon sets. Some have one member polygon 
(a,b,c), while the rest (d,e,f) have two or more. 
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a. Convex polygon. b. Concave polygon. 



c. Self-Intersecting d. Polygon-set with three 

polygon. non-overlapping member 

polygons. 



e. Polygon-set with two f. Polygon-set with one 

Intersecting member polygon member enclosed 

polygons. In another. 


Figure 2-4. Examples of Polygon Sets 
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NPOINT specifies the number of vertices in the polygon set. XVEC and YVEC 
are arrays specifying the vertex locations in world coordinates. OPCODE is 
an array which holds opcodes corresponding to each vertex in the polygon 
set. The opcode for a vertex indicates whether it is the beginning vertex 
of a member polygon or whether it is a subsequent one. If it is a sub¬ 
sequent vertex» the opcode indicates whether the edge which connects this 
vertex with the previous one is a displayable edge or a non-displayable 
edge. 

The first vertex specified in XVEC and YVEC must have the proper OPCODE 
value for the beginning vertex of a member polygon. ZPGDI and ZPGDD move to 
this first vertex and use the subsequent vertices to define the edge of the 
first member polygon until NPOINT vertices are processed or a vertex is 
reached which is marked as the beginning of a new member polygon. 

In either case, if the last vertex of the member polygon is not the sajne as 
its first vertex, DGL adds a non-displayable edge to close the figure. If 
NPOINT vertices have not been processed, DGL processes the next member 
polygon in the same way. Vftien the entire polygon set is finished, the 
starting position for the next primitive is at the first vertex of the last 
member polygon. 

ZPGDD does a fast approximation to a polygon set in the polygon, but the 
results will vary with the capablities of the display device since ZPGDD 
makes use of its available polygon functionality. ZPGDD instructs the 
device to approximate visible polygon edges when the polygon style indicates 
that edges are to be displayed. If the device cannot generate any polygon 
edges, ZPGDD will simulate the functionality. 

If filling is requested, ZPGDD instructs the device to fill the polygon set 
in a device-dependent approximation of the current polygon style. If the 
device cannot meet the request for fill at all, ZPGDD will not simulate fill 
functionality. 

However, when no fill is output although requested, aoid the polygon style 
indicates that edges are not to be displayed, ZPGDD will generate an outline 
of the polygon set so that there will be some representative visible output. 
ZPGDD will generate this outline in the interior fill color and interior 
linestyle and will output only those edges which have an opcode indicating 
that they are displayable. 

ZPGDI, by contrast, generates polygon sets with software; it will not use 
the polygon capabilities of the device unless it could do so accurately for 
the entire style range. ZPGDI creates polygon sets with reasonable accuracy 
and uniformity on all devices, but on some not as quickly as ZPGDD. 
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Alphanumeric Output 


21ALPH (NCHARS, STRING) Output to the alphanumeric display 

Alphanumeric strings can be used to prompt for operator input, give status 
reports, or output debugging messages. Because this output is not graphi¬ 
cal, it is not affected by the graphics primitive attributes. A typical al- 
pheuiumeric device is a terminal. 

A call to ZALPH sends the first NCHARS number of characters contained in ar¬ 
ray STRING to the alphauivuneric device. A carriage-return line-feed (CRLF) 
will normally be appended to STRING before it is sent to the device. If an 
underscore is the last character of the string sent out, the CRLF will be 
suppressed and the underscore will not be displayed. 

If the alphanumeric display is physically the same device as the graphics 
display device, there are some restrictions as to idiat may be passed in 
STRING. Any escape codes which affect the graphics display should not be 
sent, since they may place the graphics display in an \inknown state. The 
following program illustrates how ZALPH could be used to tell the operator 
that the graphics is complete. 


INTEGER MSG(17) 

DATA MSG/2HGr,2Hap,2Hhi,2Hng,2H o,2Hf ,2Hth,2He , 

* 2Him,2Hag,2He ,2His,2H c,2Hom,2Hpl,2Het,2He / 


CALL HOUSE * Subroutine to generate the house 

CALL TREE * Subroutine to generate the tree 

C 

C Use ZALPH to tell the operator 'Graphing of the image is complete 
C 

CALL ZALPH (3U,MSG) 
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PRIMITIVE ATTRIBUTES 


Primitive attributes determine the appearance of the graphics output. 
Attributes are divided into two clases: attributes that apply to polygon 
interiors and attributes that apply to all other graphics primitives. As an 
example, the linestyle attribute specifies the pattern (such as solid or 
dashed) in tdiich DGL draws lines. There are two separate linestyle at¬ 
tributes: one that applies to polygon interiors and another that applies to 
all other line segments. 

Table 2-2 shows how attributes affect graphics primitives. Notice that 
highlighting affects all primitives, including polygon interiors. However, 
there are two distinct color attributes: the 'color' attribute that only 
affects primitives outside of polygons and a second color attribute, 
'polygon color' that only affects polygon interiors. 


Table 2-2. How Attributes Affect Graphics Primitives 


ATTRIBUTE 



PRIMITIVE 




Line 

Polyline 

Marker 

Text 

Polygon 

Edge 

Polygon 

Interior 

Color 

X 

X 

X 

X 

X 


Highlighting 

X 

X 

X 

X 

X 

X 

Linestyle 

X 

X 


X 

X 


Linewidth 

X 

X 


X 

X 


Character Size 




X 



Polygon color 






X 

Polygon linestyle 






X 

Polygon style 






X 


Attributes will be applied to each primitive according to the devices' 
capabilities. For instance, an HP 9872 plotter can apply linestyle to lines 
and polylines, but not to text. See the Device Handlers Manual for a 
description of device capabilities. 
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DGL maintains a table of values for each attribute. When DGL enables a 
graphics device, each table is initialized with default values suited to the 
device. The value of the current entry can be inquired, or a different 
entry chosen, as long as the graphics display device stays enabled. Except 
for the color and polygon-style tables, entries in the attribute tables can¬ 
not be redefined. 


Color 


Choose color model 
Choose color for graphics primitives 
except polygon-set interiors 

ZDCOL (COLOR,COLPl,COLP2,COLP3) Redefine entry in color table 

ZPICL (COLOR) Choose color for polygon-set interiors 

Every graphics device h 2 indler in DGL has its own default color table. For 
some devices, the size of the color table may be changed before program ex¬ 
ecution. Every default color table has at least an entry at index 1 and 
display devices for which there is a backgroiind color have an entry at index 
0. Color 1 is the default color for all primitives and color 0 is the 
background color of the display device. 

The user who does not wish to use the default color 1 for all primitives may 
choose other entries in the color table to be used instead. The color entry 
to be used for polygon interiors is chosen independently of the color entry 
to be used for all other primitives. When ZPICL is called the color entry 
specified is the color entry used to output subsequently defined polygon in¬ 
teriors. A call to ZCOLR specifies an entry that is applied in the same way 
to all other output primitives. 

The user may redefine a color table entry using ZDCOL. A new color value 
for the entry specified in parameter COLOR is set according to the values of 
the parameters COLPl, C0LP2 and C0LP3. When the value of a color entry is 
redefined through ZDCOL, einy subsequently output primitives which use that 
entry will reflect the newly defined value. The effect of redefinitions on 
previously output primitives is device dependent. 

ZDCOL accepts color definitions in two color models, RGB and HSL. ZCOLM al¬ 
lows the user to specify which color model should apply to subsequent calls 
to ZDCOL. RGB is the default specification. When ZCOLM is called, it does 
not affect color definitions previously made using another model. When the 
value of a color table entry is inquired, it is returned in the current 
model, which may not be the model in which it was originally specified. 


ZCOLM (MODEL) 
ZCOLR (COLOR) 
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The RGB model, shown in Figure 2-5» is a color cube with the primary addi¬ 
tive colors, red, green and blue, as its axes. Each point within the cube 
has a red intensity value (X coordinate), a green intensity value (Y coor¬ 
dinate) and a blue intensity value (Z coordinate). Each axis or intensity 
ranges from zero to one, and each point defines a unique color. 


CYAN WHITE 

( 0 , 1 , 1 ) ( 1 , 1 , 1 ) 



Figure 2-5. Red-Green-Blue Color Cube 


The HSL model, shown in Figure 2-6, is a color cylinder in which: 

o The angle about the axis of the cylinder, in fractions of a circle, 
is the hue. 

o The radius is the saturation. 

o The height is the luminosity (intensity or brightness per unit 
area). 


Angle, radius and height all range from zero to one, and each point within 
the cylinder defines a unique color with a hue value, a saturation value, 
and a luminosity value. 
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The RGB model is most useful in applications where the primary colors are 
used. For exeunple, in printed circuit board artwork layout, colors are used 
to distinguish between different material layers. Here the user does not 
care how bright the shade of red is, but simply that the color red is used. 

The HSL model, however, is easier to use when objects are shaded to simulate 
three-dimensional curvature. In this case, conceptual features like satura¬ 
tion and luminosity enable the display of shaded polygons, taking into ac- 
covmt the light sources, polygon characteristics, aind the positions and 
orientations of the polygons and sources. 



Figure 2-6. Hue-Saturation-Luminosity Color Cylinder 
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In summary: 

to display a graphics primitive in a particular color may require any or all 
of the following actions: 

o In the Device Handlers Manual^ search the default color table of the 
graphics display device for a color index that will produce the 
desired color. 

o If the desired color is not in the default table, call ZCOLM to 
switch to a different color model. Call ZDCOL to change the color 
definition assigned to an index. 

o To specify the color of subsequent graphics primitives, call ZPICL 
for polygon interiors, ZCOLR for line primitives. 


Highlighting 


ZHIGH (HIGH) Set highlighting 

Highlighting is a means of emphasizing portions of an image. The DGL system 
provides a highlighting attribute to control the way that graphics output is 
displayed on the graphics device. A device may perform highlighting by 
blinking or intensifying certain output primitives. There is a maximum of 
23 ^ types of highlighting, but the actual number supported on the graphics 
display is device dependent. The mapping between the value of the high¬ 
lighting attribute and the types of highlighting supported is also device 
dependent, with the exception of the value of 1 which never produces 
highlighting. 

If highlighting is not supported on the selected graphics display device, 
the attribute value will be set to 1. The DGL display device initialization 
also sets the value of the attribute equal to 1. 


LInestyle 

ZLSTL (LSTYLE) Choose linestyle for graphics primitives 

except polygon-set interiors 

ZPILS (LSTYLE) Choose linestyle for polygon-set interiors 

Each graphics device handler in DGL has a fixed linestyle table, shown in 
the Device Handlers Manual . DGL maintains two indices to the table of the 
current device: one for the hatch lines used to fill polygon interiors, and 
one for other graphics primitives except markers. Markers are always drawn 
using solid lines. 
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Both linestyle indices are set to 1 at display device initialization. ZPILS 
chooses the index for the interiors of subsequent polygon sets. ZLSTL 
chooses the index for lines, polylines, graphics text characters, and the 
edges of polygon sets. 

A linestyle is a recurring pattern of dots, blanks, short line segments and 
long line segments. In DGL, a linestyle cam be drawn in any of three types: 
start-adjusted, continuous, or vector-adjusted. The available types depend 
on the device. On some devices, for instance, all linestyles are drawn in a 
continuous manner. 

Start-adjusted linestyles always begin a vector with the first elements of 
the specified pattern. For exaunple, if a pattern starts with two dots, each 
vector drawn will start with two dots. Likewise, if the vector starts with 
five blank spaces and then a dot, each vector drawn will start with five 
blank spaces. In the second example, if the vectors are short, the pattern 
may not be displayed at all if the vector is not longer th 2 Ui the section of 
blanks. This type of linestyle will usually degrade idien attempting to draw 
smooth curves with many small line segments. 

Continuous linestyles start the pattern with the first vector, but sub¬ 
sequent vectors will be continuations of the pattern. Thus it may take 
several vectors to complete one cycle of the patteni. This type is useful 
for drawing smooth curves, but does not necessarily reproduce either 
endpoint of the vector. As with start adjusted linestyles, if a vector is 
small enough, it might be composed only of the space between points or 
dashes in the pattern. In this case, the vector may not be displayed at 
all. 

With vector-adjusted linestyles, each vector is treated individually. 
Individual treatment guarantees that a solid component of the pattern will 
be generated at both ends of the vector. Thus, the endpoints of each vector 
will be clearly identifiable. Linestyle integrity degenerates with very 
small vectors. Since some component of the pattern must appear at both ends 
of the vector, a short vector will often be drawn as a solid line. 

Figure 2-7 illustrates how one pattern would be displayed using each one of 
the different linestyle type. 
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START ADJUSTED 


CONTINUOUS 


VECTOR ADJUSTED 


LINESTYLE USED 

Figure 2-7. Types of Linestyles 


Linewidth 


ZLWID (LWDTH) Set the.linewidth 

A programmer may output lines of different widths by changing the linewidth 
attribute. A call to subroutine ZLWID sets the linewidth attribute for sub¬ 
sequent lines, polylines, polygon edges, and graphics text characters. 
Markers are not affected by this call because they are defined to always be 
output using the thinnest linewidth supported on the graphics display 
device. 

All devices support at least one linewidth. The number of supported widths 
is device dependent. A value of 1 always specifies the thinnest width pos¬ 
sible. When multiple widths are supported, the width of the line increases 
as the value of LWDTH does, \mtil the device-supported maocimum is reached. 
If LWDTH is greater than the number of line widths supported by the graphics 
display, or if LWDTH is less than 1, then the linewidth will be set to the 
thinnest available width. The default value of LWDTH is 1. 





Character Size 


ZCSIZ (WIDTH, HEIGHT) Set character size 

The DGL system provides a character size attribute to control the size of 
graphics text generated. A subroutine call to ZCSIZ defines the desired 
width and height of the character cell in which characters are positioned. 
Actual sizes of text which can be generated on the graphics display are 
device dependent, as is the placement of text within the character cell. 

The desired width and height of the cell are specified in world coordinate 
system units. If the requested character size is not available on the 
graphics display, then the "smaller best fit" character size will be used. 
See Figure 2-8 for the different text widths and heights available. The 
definition of the "smaller best fit" character size is as follows: 

1. The largest character whose cell height is less than or equal to the 
requested height and whose cell width is less than or equal to the 
requested width, or, 

2. If the minimum hardware size does not meet criterion 1, the minimum 
character size is used. 


ZCSIZ (O . 035, O . 05) 


c s X ^ 

C o 

. O -X . 

o . 

OS) 

ZCSIZ 

(0 

. 07, 

0 . 

1) 


ZCSIZ (0.035, 0.1) 

Figure 2-8. Different Text Widths and Heights 
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Polygon Style 


ZDPST (PINDEX.DENSTY,ORIENT,EDGE) Redefine entry in polygon style table 

ZPSTL (PINDEX) Choose polygon style 


Polygon style has three components: 

o DENSTY is the density of fill lines used to fill the interiors of 
polygon sets. Density ranges from no fill to solid fill. A posi¬ 
tive density mews fill lines in one direction only (all parallel); 
a negative density means perpendicular cross-hatching. 

o ORIENT is the angle of interior fill lines to the horizon, ranging 
from - 90.0 degrees to + 9 O.O. For cross-hatching, the wgle refers 
to the first set of hatch lines, with the second set perpendicular 
to the first. 

o EDGE defines Aether the segments of the edge of a polygon set which 
are defined as "draw" segments (in ZPGDI or ZPGDD) should be dis¬ 
played. Edge segments specified as "move" segments are never dis¬ 
played. Displayed edge segments are drawn using the entries 
specified by ZCOLR, ZLSTL and ZLWID. 

Every graphics device handler in DGL has a default polygon style table. The 
number of entries in the table and their values depend on the graphics 
device. Default definitions are designed to suit each graphics device. The 
first 16 styles are the same for all devices (see Figure 2-9). For some 
devices, entries can be added to or deleted from the table before program 
execution. 

When ZPSTL is called, specifying an index into the polygon table, the 
polygon style defined by this entry overrides any previously chosen polygon 
style and is then the polygon style used to output subsequently defined 
polygon sets. 

The user may redefine an entry in the polygon style table using ZDPST. When 
the value of a polygon style entry is redefined through ZDPST, any sub¬ 
sequently output polygon sets which use that entry will reflect the newly 
defined value. 
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VIEWING TRANSFORMATIONS 


General 


A viewing traucis format ion is the method by which objects are turned into 
viewable images. DGL's viewing transformations modify objects for viewing 
by transforming them from the units in which they were defined to device¬ 
dependent units (see Figure 2-10). 


OBJECT 


IMAGE 

• TWO-DIMENSIONAL 

_K 

• TWO-DIMENSIONAL 

• APPLICATION-DEPENDENT 

UNITS (INCHES, MILES, ETC.) 


VIEWING N. 

TRANSFORMATION ^ 

• DEVICE-DEPENDENT UNITS 

• ONE OR MORE OUTPUT 
PRIMITIVES 




Figure 2-10. The Viewing Transformation 



Graphics primitives are used to create two-dimensional objects in the world 
coordinate system. A number of concepts are important in understauiding how 
DGL turns two-dimensional objects in the world coordinate system into images 
on a display device. The DGL viewing trains format ion is summarized in 
Figure 2-11. 



VIRTUAL 

COORDINATE 

SYSTEM 


VIEWPORT 


Figure 2-11. The DGL Viewing Transformation Process 
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Three questions must be addressed when defining the DGL viewing 
trains format ion: 

1. What portion of the world coordinate system will be used to define 
and display the object (where is the nindois)? 

2. Where will the window be mapped in the virtual coordinate system 
(where is the vieiipovt)? 

3 . Where will the virtual coordinate system be placed on the physical 
display surface (what are the logical display limits )? 

The window defines the portion of the world coordinate space to be used. 
This provides the application program with the flexibility of working in 
units that are relevant to the application. If the elements of an object 
extend beyond the limits of the window, the resulting image may appear to 
mn off the edges of the display surface, since software clipping is not 
done by DGL. This phenomenon is not well defined because out-of-range world 
coordinate data is h^uldled in a device-dependent manner. Refer to the 
Device Handlers Manual to see how a particular device handles this problem. 

The user also has control over the virtual coordinate system, the two- 
dimensional system whose units range from 0.0 to a maximum of 1.0. Since 
many display devices do not have the same aspect ratio, the placement of 
the virtual coordinate system on the logical display surface requires plan¬ 
ning. If the virtual coordinate system were always a unit square, a non¬ 
square logical display surface would not be entirely available. To make 
full use of a non-square logical display surface, DGL allows the aspect 
ratio of the virtual coordinate system to be changed as needed. 

The size and shape of the logical display surface is also imder the user's 
control. Logical display limits allow a subset of a display device to be 
used for output. The bed of a plotter might be 500 millimeters by 1000 mil¬ 
limeters, while the paper used in it might be only 250 millimeters square. 
The logical display limits of the plotter can be set to that size, so that, 
from that point on, DGL would treat the plotter as if it were physically 250 
millimeters square. 

The logical display limits determine the size and placement of the view sur¬ 
face. The view surface's dimensions and placement are determined by: 

1. The aspect ratio of the virtual coordinate system, and 

2. The logical display limits of the display device. 

Once the view surface is determined, a portion of it is designated to be the 
vieivport. An application might use several viewports to show different 
views of the same object. Since the window is mapped directly onto the 
viewport, distortion may result if the window does not have the same aspect 
ratio as that of the viewport. This type of distortion is illustrated in 
Figure 2-12. 
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VIEWPORT 



WINDOW 

Figure 2-12. Distortion in the Window to Viewport Mapping 


Logical Display Limits 


ZDLIM (XMIN,XMAX,YMIN,YMAX,im) Set logical display limits 

ZDLIM sjjecifies a subset of a physical display surface to be used for 
graphics output. ZDLIM defines the logical display limits. The limits of 
this area are expressed in terms of millimeters offset from the physical 
origin of the device. The location of the physical origin of a display 
device is device dependent (see the Device Handlers Manual). 

The virtual coordinate system is mapped onto the largest region within the 
logical display limits which has the aspect (height to width) of the virtual 
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coordinate system. Therefore, the displayed image will not be distorted; it 
will merely be scaled smaller or larger. 


Aspect Ratio 


ZASPK (WIDTH, HEIGHT) Set aspect ratio of virtual coordinate system 

ZASPK sets the aspect ratio of the virtual coordinate system (and hence the 
aspect ratio of the view surface) to be HEIGHT divided by WIDTH. A ratio of 
1.0 defines a square virtual coordinate system; a ratio greater thaui 1.0 
specifies it to be higher than it is wide; and a ratio less than 1.0 
specifies it to be wider than it is high. Since WIDTH and HEIGHT are used 
to form a ratio, they may be expressed in any xmits (as long as they are in 
the same units). 

DGL calculates the range of the coordinates of the virtual coordinate system 
based on the value of the aspect ratio as shown in Table 2-3. The coor¬ 
dinates of the longer axis are always set to rauige from 0.0 to 1.0, and 
those of the shorter axis from 0.0 to a value that achieves the specified 
aspect ratio. Thus, ZASPK also defines the limits of the virtual coordinate 
system. 


Table 2-3. Virtual Coordinate Limits 


Aspect Ratio (AR) 

X Limits 

y limits 

AR < 1.0 

0.0, 1.0 

0.0, 1.0*AR 

AR = 1.0 

0.0, 1.0 

0.0, 1.0 

AR > 1.0 

0.0, 1.0/AR 

0.0, 1.0 


When a call to ZASPK is made, the DGL system sets the viewport equal to the 
limits of the virtual coordinate system. This call can therefore be used to 
access the entire logical display surface. A program could display an image 
on the entire logical display surface in the following manner: 
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INTEGER ILIST, lERR 

REAL MAXS(2), WIDTH, HEIGHT 


CALL ZIWS (253, 0, 2, ILIST, MAXS, 


WIDTH = MAXS(l) 

HEIGHT - MAXS(2) 

CALL ZDLIM(0,WIDTH,0.,HEIGHT,lERR) 


CALL ZASPK(WIDTH,HEIGHT) 


* Get the dimensions 
lERR) * of the display 

* surface. 

*Width of the physical display 
*surface. Height of the physical 
•display surface. Set logical 
•limit to their maximum. 

•Set the aspect ratio of the 
•virtual coordinate system to 
•the maximum aspect ratio of 
•the display surface. 


The initial aspect ratio of the virtual coordinate system is 1.0, meaning 
the virtual coordinate system is a unit square. This produces a view sur¬ 
face that is the largest inscribed square within the logical display limits. 
By changing the aspect ratio, the view surface defines the largest inscribed 
rectangle within the logical display limits. The placement of the view sur¬ 
face is dependent upon the device being used. It is generally centered on 
CRT displays and is usually placed in the lower left-hand comer of plot¬ 
ters. Refer to the Device Handlers Manual to determine the placement of the 
view surface on the logical display surface of a particular display device. 


Viewport 


ZVIEW (VXMIN,VXMAX,VYMIN,VYMAX) Set the viewport 

ZVIEW sets the limits of the viewport in \uiits of the virtual coordinate 
system. The viewport must be within the limits of the virtual coordinate 
system. The initial viewport is: 

(VXMIN=0.0, VXMAX=1.0, VYMIN=0.0, VYMAX=1.0) 

This initial viewport is mapped onto the msocimum visible square within the 
logical display limits. This area is called the view surface. 

By changing the limits of the viewport, an application program can display 
an image in several different positions on the ssime display surface. Figure 
2-13 illustrates how an image could be displayed sequentially in the four 
comers of a display surface. 
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REAL AR(2), VMAXX, VMAXY 
INTEGER ILIST, lERR 

CALL ZIWS (25lt,0,2,ILIST,AR,IERR) 


VMAXX = 1.0 
VMAXY = 1.0 

IF (AR(2).LT.1.0) VMAXY = AR(2) 

IF (AR(2).GT.1.0) VMAXX = 1.0/AR(2) 
VMIDX = VMAXX/2.0 
VMIDY = VMAXY/2.0 

CALL ZASPK(1.0,AR(2)) 


CALL ZVIEW(0.0,VMIDX,VMIDY,VMAXY ) 
CALL HOUS(XHOUS,YHOUS) 

CALL TREE(XTREE,YTREE) 


CALL ZVIEW(VMIDX,VMAXX,VMIDY,VMAXY) 
CALL HOUS(XHOUS,YHOUS) 

CALL TREE(XTREE,YTREE) 


CALL ZVIEW(0.0,VMIDX,0.0,VMIDY) 
CALL HOUS(XHOUS,YHOUS) 

CALL TREE(XTREE,YTREE) 


CALL ZVIEW(VMIDX,VMAXX,0.0,VMIDY) 
CALL HOUS(XHOUS,YHOUS) 

CALL TREE(XTREE,YTREE) 


^ Get the aspect ratio of the 
^ logical display surface. 

^ Determine the virtual 

* coordinate bounds given 
^ the maximum 

* aspect ratio: 

* middle of X range 

* middle of Y range 

^ Set the aspect ratio of the 

* virtual coordinate system to 
^ the aspect ratio of the 

^ display surface. 

^ Viewport 1 -- 
^ Set viewport to upper left- 
^ hand comer and draw the 
^ house and tree. 


* Viewport 2 -- 
^ Set viewport to upper right- 
^ hand comer aind draw the 
^ house auud tree. 


* Viewport 3 
^ Set viewport to lower left- 
^ hand comer and draw the 
^ house and tree. 


* Viewport U -- 

* Set viewport to lower right- 
^ hand comer and draw the 

^ house and tree. 
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Figure 2-13. Multiple Viewports 
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Window 


ZWIND (WXMIN,WXMAX,WyMIN,WYMAX) Set the window 

ZWIND specifies the portion of the world coordinate system that maps onto 
the viewport. Setting the window allows the application program to define 
vdiich portion of the world coordinate space is to he viewed. This provides 
the application prograun with the flexibility of working in units that are 
relevant to the application. Since the window is in the same coordinate 
space in which objects are defined, the bounds of the window can affect the 
size of the image displayed. The larger the limits of the window, the 
smaller the object's image. If, however, the window is specified as having 
smaller limits than the object, unpredictable, device-dependent results oc¬ 
cur, since the DGL system does not perform software clipping. 

The window is defined in units of the world coordinate system. The window's 
aspect ratio should be the saime as the aspect ratio of the viewport if dis¬ 
tortion is not desired. In general, setting the window by calculating its 
dimensions as a fimction of the viewport is a good way to prevent distor¬ 
tion. In this way, no assumption is made about a previously set viewport, 
helping to ensure that the visual results will be those desired. 

The initial window has the following limits, expressed in world coordinate 
vmits: 

(WXMIN=-1.0, WXMAX=1.0, WYMIN=-1.0, WYMAX=1.0) 

The default aspect ratio of the window is 1.0, which is the same as the 
aspect ratio of the initial viewport. 


Conversion of Units 


2DPMM (WX,WY, MMX , MMY ) Convert a world coordinate point to millimeters for 

the physical graphics display device. 

The DGL system provides the user with the capability to detemine where a 
coordinate point in the world coordinate system will be displayed on a 
graphics display surface. A subroutine call to ZDRIM returns the location 
that the world coordinate system point (WX,Wy) is mapped to on the graphics 
display. The coordinate returned in (MMX,MMY) is expressed as the mil¬ 
limeters offset from the origin of the physical graphics device. The loca¬ 
tion of the origin is device dependent. Refer to the Device Handlers 
Manual for the position of the origin on a specific device. 
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INPUT PRIMITIVES 


General 


The DGL system has a class of functions i^ich enable a user to interact with 
an application program. These functions, or input primitives, provide a 
method for receiving input. Each primitive is implemented by an input 
device. A DGL application program can receive input from the following 
devices: 

1. Button - returns an integer 

2. Keyboard - returns alphanumeric text 

3. Locator - returns an (X,y) point 

k. Valuator - returns a real value between 0.0 and 1.0 

Data can be obtained from these devices in two different ways: requesting 
and sampling. A device is said to request data when it waits for an 
operator response, such as striking the carriage return, before returning 
information. Data can be requested from every input device. Sampling means 
that the current value of the device is returned without waiting for any 
operator response. Sampling may only be performed on locator and valuator 
devices. 

One DGL application program can receive input from at most one of each of 
the four input devices. Some input devices are not supported directly by a 
physical device, but are simulated by the DGL software. As eui example, the 
valuator device is simulated on the HP 2623 Graphics Terminal by using 
either the X or Y coordinate of the graphics cursor. 

Another important feature is echoing. Echoing gives an operator instan¬ 
taneous feedback during an input operation. Some echoes reflect the status 
of the input operation so as to allow refinement before completion. A 
familiar example of echoing is the characters that appear on a terminal 
screen when a key is pressed. In most systems, these characters have ac¬ 
tually been echoed by the computer after it has received them from the 
keyboard. By seeing what is typed, an operator may correct any typographi¬ 
cal errors before terminating the input operation by pressing return. 

The type of echoing depends on the type of input being requested auid the 
properties of the device being used. The echo itself begins when the input 
operation is initiated and lasts only until the operation is terminated. 

There are two types of echoes: those on the input device itself suid those on 
the graphics display device. All input functions may be echoed on the input 
device (depending, of course, on the device's echoing capabilities). 
Locator input may also be echoed on the graphics display device. These 
echoes begin at a user-defined point called the locator echo position. Some 
display device echoes also utilize this point throughout the echo. For 
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example, when a rubber band line echo is used with locator input, the fixed 
end of the rubber band line begins at the locator echo position. 


Button 


ZBUTN (ECHO, BUTTON ) Request button input 

The button device returns an integer value associated with the button 
pressed. When ZBUTN is called the application program waits until the user 
presses a button and an integer is returned in BUTTON. The integer ranges 
from 1 to a device-dependent’ meocimum (it will never be greater than 255 )- 
Zero will be returned if ain invalid button is activated. 

Typical button devices are the numeric keys of an interactive keyboard or 
special function keys. Echoing is specified by the value of ECHO. A value 
of 0 indicates that no echo should be performed. Possible echoes include 
turning on a light or beeping when a button is activated. 


INTEGER BUTTON * Buttons are always integers. 

50 CONTINUE 

CALL ZBUTN(0,BUTTON) 

IF (BUTTON.EQ.l) GOTO 
IF (BUTTON.EQ.2) GOTO 
IF (BUTTON.EQ.3) GOTO 
GOTO 50 


100 

200 

300 


* Branch based on the value of 

* the button. 

* If out of range, 

* try again. 
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Keyboard 


ZKYBD (ECHO, MAX, ACTUAL , STRING ) Request keyboard input 

The keyboard device returns an alphanumeric text string to the calling 
program. A call to ZKYBD waits until a line of text has been entered on the 
keyboard device and is terminated (e.g. carriage return) before the text is 
returned in the array STRING. The characters are returned in Packed ASCII 
format. The termination character is not returned in STRING. A MAX number 
of characters may be entered, with the restriction that MAX be less than or 
equal to 132. The actual number of characters entered is returned in 
ACTUAL. 

Echoing, as specified by the ECHO parameter, depends upon the capabilities 
of the physical device being used. In all cases, 0 indicates that echoing 
should not be performed. Possible echoes include sounding a bell or dis¬ 
playing the input as it is entered. Refer to the Device Handlers Manual 
for echoes supported by a particular device. 


INTEGER ACTUAL,STRING(20) 


* UO characters 


CALL ZKYBD(1,1*0,ACTUAL,STRING) 
CALL ZTEXT(U0,STRING) 


Request up to UO characters 
with echo 1 and output them 
on the graphics display. 


Locator 

GENERAL 


The locator device returns an (X,Y) point in the world coordinate system. 
This position may either be sampled or requested. Typical locator devices 
are digitizers and graphics cursors on CRTs. At least one type of echoing 
csin always be performed. The number and type of echoes available is depen¬ 
dent upon the device being used, as well as the method of inputting data. 



LOCATOR LIMITS 


ZLLIM (XMIN, XMAX, YMIN, YMAX, lERR ) Set the locator limits. 

ZLPMM (WY, WY, MMX , MMY ) Convert a world coordinate point to 

a point on the physical locator 
device. 


Just as a portion of the display surface was selectable for graphics output, 
portions of the locator surface may be selected for input. This is done by 
setting the limits of the locator surface. The limits of the locator are 
initially defined as the addressable area of the locator device. ZLLIM al¬ 
lows the user to set these limits to a different region on the locator sur¬ 
face. The pairs (XMIN,YMIN) and (XMAX,YMAX) define the comer points of 
this rectangle in terms of millimeters offset from the origin of the device. 
(The exact position of the device origin is device dependent and is docu¬ 
mented in the Device Handlers Manual .) 

ZLLIM does not affect the virtual coordinate system. It only affects the 
mapping from the virtual coordinate system to the locator surface. 

If the locator and the graphics display are both the same physical device 
(i.e., HP 2623 display and HP 2623 cursor), then the locator limits and the 
display limits must be identical. Specifically, when they refer to the same 
surface, the interaction between ZDLIM and ZLLIM is as follows: 

1. The locator limits are initialized to the same values as the logical 
display limits. 

2. A call to ZDLIM implicitly calls ZLLIM with the same values. 

3 . Explicit calls to ZLLIM are ignored. 

The logical locator limits always map directly to the view surface, there¬ 
fore, distortion may result in the mapping between the logical locator and 
the display when the logical locator limits and the view surface have dif¬ 
ferent aspect ratios. If this distortion is not desired it can be avoided 
by assuring that the logical locator limits maintain the same aspect ratio 
as that of the view surface. 

ZLPMM converts a world coordinate point to millimeters on the locator 
device. (V?X,WY) cam be auiy world coordinate point. It does not have to be 
in the window or map to a point on the time physical limits of the locator. 
(MMX,MMY) is expressed in millimeters offset from the origin of the locator 
device. The position of this origin is device dependent. Refer to the 
Device Handlers Manual for its location on a particular device. 
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SAMPLING THE LOCATOR 


ZSLOC (ECHO,WX,WY) Sample locator and report value 

ZSLOC returns the current position of the locator in world coordinates 
(WX,Wy) without waiting for an operator request. 

The nxunber of echoes supported by a device and the relationship between the 
value of ECHO and the echo performed is device dependent (refer to the 
Device Handlers Manual). A value of 0 always specifies that echo should not 
be performed. 


REQUESTING LOCATOR INPUT 


ZWLOC (ECHO, LBUTN, OT) Request locator input, report value 
ZLOCP (WX, WY) Set the locator echo position 

A call to ZWLOC causes the application program to wait until a locator but¬ 
ton is pressed. The value of the selected button and a world coordinate 
point (WX,WY') are then returned to the calling program. Each locator device 
has its own set of buttons which may or may not be the same as those that 
comprise the button device. If an invalid button is pressed, LBUTN will be 
returned as 0; otherwise, LBUTN will contain the value of the button 
activated. 

Several different t 3 rpes of echoing can be performed. Some echoes are per¬ 
formed only on the locator device. Possible echoes include blinking a light 
or sounding a bell each time a point is entered. The number and relation¬ 
ship between the value of ECHO auid the echo performed is dependent upon the 
locator device being used (refer to the Device Hauidlers Manual). 

Some locator echoes are performed on a graphics display device. All locator 
echoes on the graphics display begin at a world coordinate point called the 
locator echo position. Some echoes may also use the locator echo position 
as a reference point. For example, many devices support a rubber band line 
echo. The fixed end of the rubber band line will be at the locator echo 
position. ZLOCP sets the value of this world coordinate point to (WX,Wy). 
Note that the locator echo position is not releveint to ZSLOC, only to ZWLOC. 

The point (WX,WY) specified in the ZLOCP call must be displayable to be able 
to use echoing. Therefore, it cannot be specified outside the current world 
coordinate limits or an error will result amd the call will be ignored. The 
default locator echo position is in the center of the window. When a call 
is made which changes either the viewing trains format ion or the mapping be¬ 
tween the display surface and locator surface, the locator echo position is 
reset to its default value. The calls which do this are ZASPK, 23DLIM, 
ZLLIM, ZDINT, ZLINT, ZWIND and ZVIEW. 
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The following program section shows a use of these calls. The locator 
device is used to let the operator set the locator limits interactively by 
selecting the lower left comer first, then the upper right comer. 


# 

CALL ZVn.OC(0,LBUTN,WXMIN,WYMIN) 

CALL ZLOCP(WXMIN,WYMIN) 

CALL ZWLOC(h,LBllTN,WXMAX,WYMAX) 

CALL ZLPMM(WXMIN,WYMIN,MXMIN,MYMIN) 

CALL ZLPMM(WXMAX,WYMAX,MXMAX,MYMAX) 

CALL ZLLIM(MXMIN,MXMAX,MYHIN,MYHAX,IERR) 


^Request locator input with no 
*echo. 

*Set the locator echo position. 
^Request locator input using 
^rubber band echo. 

*Convert both points to 
^millimeters on the locator. 

*Set the locator limits to them. 


Valuator 


GENERAL 


A valuator returns a single real value ranging from 0.0 to 1.0. Some 
valuator devices are composed of multiple subvaluators. The subvaluator 
specifies which valuator will be used. For example, on the HP 2623 Graphics 
Terminal, subvaluators can be simulated by using either the X coordinate or 
the Y coordinate of the graphics cursor as the valuator. If the subvaluator 
equals 1, the X coordinate of the cursor is returned with 0.0 representing 
the extreme left side of the display and 1.0 representing the extreme right 
side. If the subvaluator equals 2, the Y coordinate of the cursor is 
returned, with 0.0 represented as the bottom of the display and 1.0 
represented as the top of the display. 

Echoing can be performed on the valuator device when either sampling data or 
requesting data. The number and type of supported echoes are device depen¬ 
dent, but the majority of valuators support at least one tjrpe of echoing. 
Possible echoes include beeping 2 ind displaying the value each time the 
valuator is sampled. A value of 0 for the echo specifies that echoing will 
not be performed. 
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SAMPLING A VALUATOR 


ZSVAL (ECHO,SUBVAL, VALUE ) Sample the valuator and report value 

ZSVAL returns the current value of the valuator in the variable VALUE 
without waiting for operator response. VALUE will always range from 0.0 to 
1.0. The program specifies the desired echo in ECHO and the subvaluator in 
SUBVAL. Valuators are sampled in applications that require cheinging some 
attribute of the program in real time. 


REQUESTING A VALUATOR 


ZWVAL (ECHO,SUBVAL, VBUTN , VALUE ) Request valuator input emd report value 

A call to ZWVAL causes the application program to wait until a valuator but¬ 
ton is pressed. The value of the selected button is then returned in VBUTN 
and the value of the specified valuator is returned in VALUE. Each valuator 
device has its own set of buttons which may or may not be the same as those 
that comprise the button device. If an invalid button is pressed, VBUTN 
will be returned as 0; otherwise, the integer value of the button that was 
pressed will be returned. 

VALUE will always rauige from 0.0 to 1.0, and the desired echo and sub¬ 
valuator are specified in the respective variables ECHO and SUBVAL. Refer 
to the Device Handlers Mantuzl for the echoes and subvaluators supported on 
a particular device. 


CONTROL 


General 


This section discusses initialization and termination, inquiry, timing and 
escape functions. 


System Initialization and Termination 


ZBEGN Initialize the DGL system 

ZEND Terminate the DGL system 

The DGL system provides one subroutine to initialize the DGL system (ZBEGN) 
and another to terminate it (ZEND). The system must be initialized before 
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ainy other DGL subroutine is called. A subroutine call to ZBEGN must be the 
first DGL call made by the application program. When the DGL system is 
initialized, all system maintained values are set to their initial values. 

ZEND terminates the DGL system. Termination includes making the picture 
current as well as disabling and terminating all currently enabled devices. 

2£ND should be the last DGL call in an application program. 


Device Control 

GENERAL 


The DGL system is centered axovind the concepts of logical devices and a work 
station. A logical device is a hypothetical device which cam perform input 
and/or output uniformly to several different physical devices. 

Each logical device (e.g., button, graphics display device) from which any 
input will be requested or output will be sent must be enabled first. 
Likewise, every device must be disabled before the DGL system is terminated. 
The DGL system has one subroutine to enable and one to disable each device. 

A work station does not have to support every logical device. The devices 
available on a particular work station are determined by the logical device 
handlers loaded with the application program. The logical devices supported 
by a work station can be inquired from the DGL system at any time after the' 
DGL system is initialized. 

One application program can sequentially perform graphics I/O to several 
different devices of the same type. After the logical device has been dis¬ 
abled, it cam be reassociated with the same device type merely by making a 
call to reinitialize with a different value of the I/O unit descriptor. 

The I/O unit descriptor is a naune or a nxunber by which the operating system 
identifies the device. See the system supplement for details. 
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In the subroutine calls In this chapter, the term I/O \mit descriptor 
appears in italics to indicate that it is not a literal name; it must be 
replaced by the parameter or parameters appropriate to the system. 


INTEGER CONTRL.IERR 

REAL XHOUS,YHOUS,XTREE,YTREE 

CONTRL=0 

CALL ZDINT(I/O imit descriptor,CONTRL,IERR) 

. * Initialize HP 2623 graphics display. 

• 

CALL HOUS(XHOUS,YHOUS) * Draw the image on the HP 2623. 

CALL TREE(XTREE,yTREE) 

CALL ZDEND * Disable the HP 2623. 


CALL ZDINT(I/O Unit Descriptor,CONTRL 



• 


CALL 

1 

i 

1 

# 

CALL 

TREE(XTREE,YTREE) 


CALL 

ZDEND 

# 


,IERR) 

Initialize graphics display: 
a different HP 2623. 

Draw the same image on the same 
type of graphics display device. 


Disable the HP 2623. 


GRAPHIC DISPLAY DEVICE 


ZDINT (I/O unit descriptor ,CONTRL, lERR ) Enable the graphics display device 
ZDEND Disable the graphics display device 

ZDINT performs device initialization and enables the graphics display for 
output. 

The variable CONTRL can be used to specify how output will be sent to the 
device. For example, the program can specify whether graphics data can be 
outspooled, and whether the display will be cleared when it is initialized. 

ZDEND disables the graphics display device. In disabling the device, the 
DGL system makes the picture current, releases all resources being used by 
the device, and performs any termination sequences required by the device. 
It does not clear the display surface. 
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OTHER LOGICAL DEVICES 


ENABLE DISABLE FUNCTION 


ZAINT(I/O VMT DBSCRIF£0E,1EBR) 
ZBINT(I/0 VRIT DFSCfllPrOfl.IERR) 
ZKINT(I/0 VRIT DESCRlFTOEylESR) 
ZLINT(I/0 VRIT DESCEIFTOR.IESR) 
ZVINT(I/O VRIT DESCRIPTOR 


ZAEND 

Alphanumeric device 

ZBEND 

Button 

ZKEND 

Keyboard 

ZLEND 

Locator 

ZVEND 

Valuator 


With the exception of the graphics display the DGL system enables and dis¬ 
ables all devices in a similar maomer; each has one call to enable and one 
to disable the device. 

Every initialization call ensures that the picture is made current before 
attempting to initialize a device. Logical devices must be enabled before 
they are used for input or output. A logical input device caumot be enabled 
on the same physical device as that of an outspooled graphics display 
device. If aui application prograun attempts to enable a logical device that 
is currently enabled, the enabled device will be terminated and the call 
will be continued. 

Disabling a logical device causes any required termination sequence to be 
performed and all resources allocated to the device to be released. An ap¬ 
plication program should disable every logical device used before terminat¬ 
ing DGL. 


Clearing the Display Surface 


ZNEWF Clear the graphics display device 

A subroutine call to ZNEWF makes the picture current and then performs a 
new-frame-action. A new-frame-action clears the graphics display of all 
graphics output. A new-frame-action has different connotations for each 
graphics display device. The screen will be erased on CRT devices such as 
graphics terminals. Plotters with page advance will advance the paper. A 
call to ZNEWF may only make the picture current on devices such as drum 
plotters or fixed page plotters. 
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Controlling the Timing Modes 


ZMOD (OPCODE) Set the timing mode 

The immediacy by Tdiich output primitives are sent to the graphics display 
may be controlled. Whether graphics commands are immediately sent to a 
device or idiether they are placed in a buffer before being transmitted has 
a large effect on the efficiency of the DGL system and the immediacy of 
visual changes to the graphics display. The user can specify two timing 
modes, immediate visibility and system buffering. 

When in immediate visibility mode, graphics commamds will be sent to the 
display device before returning from the DGL subroutine called. Any 
requested change is displayed as it is made. This type of output is ineffi¬ 
cient, and can cause noticable system degradation. It should only be used 
in applications which require any picture changes made to the graphics dis¬ 
play device occur as they are generated. 

The alternative to immediate visibility mode, which should be used in most 
applications, is to use system buffering mode, and explicitly make the pic¬ 
ture current only at times when the picture must be current. When operating 
in this mode, requested picture changes will be placed in a buffer by the 
DGL system. The buffer is automatically flushed by DGL when the buffer is 
full. Graphics throughput will be improved since the number of data trsuis- 
fers is reduced significantly. The same information is sent to the device 
regardless of the timing mode used, but the information is sent in larger 
blocks when in system buffering mode so that fewer I/O transfers are 
required. 

On slow devices, such as plotters, the actual time it takes to plot a pic¬ 
ture may not be noticeably reduced when using system buffering mode rather 
than Immediate visibility mode. However, the amount of CPU time required 
will be less when using system buffering mode and will therefore increase 
the overall throughput of a computer system used in a multi-user or multi¬ 
tasking environment. 


Making the Picture Current 


ZMCUR Make the picture current 

The graphics display device surface can be made current at any time with 
^CUR. This ensures that all previously generated primitives have been sent 
to the graphics display device. ZMCUR does not change the timing mode. 

Many DGL functions implicitly make the picture current. For example, each 
of the input routines use it to ensure that the image is fully defined 
before the operator requests input. 
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Inquiry Functions 


ZIACS (DWIDE,DHIGH, AWIDE . AHIGH ) 
ZICOL (COLOR,C0LP1,C0LP2,C0LP3) 
ZIPST (PINDEX, DENSTY , ORIENT , EDGE ) 
ZIWS (OPCODE, machine-dependent 
parameters., ISIZE, RSI2X, 
machine-dependent parameters 
ILIST,RLIST,IERR) 


Actual size of graphics text 
Color table entry 
Polygon table entry 
Other system information 


A graphics application program can use inquiry calls in various ways. 
Inquiry calls can help debug a program, or help make it adaptable to dif¬ 
ferent input and output devices. For example, the program can ask whether 
the work station supports a logical locator device. If not, the program can 
simulate the locator device by asking the user to type the current locator 
position on a keyboard device. Thus the program stays device independent 
and flexible. 

ZIACS returns, in world coordinates, the actual character-cell width and 
height (AWIDE and AHIGH) that correspond to a desired width and height 
(DWIDE and DHIGH). This shows how closely the size of a displayed graphics 
character matches the requested size, given the capabilities of the graphics 
display device. When an exact match to the requested character size is not 
possible, ZIACS returns the nearest available size according to the "smaller 
best fit" rule (see ZCSIZ in Chapter 3)* 

Since both the both the desired and the actual sizes are in world coor¬ 
dinates, the physical size of text characters, as drawn or displayed, also 
depends on: 

o The size of the CRT screen or plotting surface, 

o The current world coordinate system, and 

o The viewing transformations in effect. 

ZICOL returns the color model values (COLPl, C0LP2, C0LP3) assigned to the 
specified index (COLOR) in the color table of the graphics device. ZDCOL 
can change the values of COLPl, C0LP2 and C0LP3. The interpretation of 
COLPl, C0LP2 and C0LP3 depends on the color model, which can be changed by 
ZCOLM. The subsection "Color" in this chapter talks about ZDCOL, ZCOLM, 
color tables, and color models. 

ZIPST returns the polygon style values (DENSTY, ORIENT, EDGE) assigned to 
the specified index (PINDEX) in the polygon style table of the graphics 
device. ZDPST can change the values of DENSITY, ORIENT and EDGE. The sec¬ 
tion in this chapter, "Polygon Style", discusses ZDPST and the meeuiings of 
DENSTY, ORIENT, and EDGE. 



ZZWS returns data on the current state of the DGL system. For details, 
refer to the section on ZIWS in Chapter 3 of this manual. One more inquiry 
call, ZIESC, is described in the next subsection. 


Escape Functions 

ZIESC (OPCODE,ISIZE,RSIZE, ILIST , RLIST , IERR ) Input escape access 

ZOESC (OPCODE,ISIZE,RSIZE.ILIST,RLIST, IERR ) Output escape access 


In addition to providing a wide variety of device-independent functions, the 
DGL system provides a mechainism to access some capabilities of devices that 
are not supported in a device independent manner. For example, the HP 7580 
Drafting Plotter has a built-in circle generator. The mechamism by idiich 
these hardware features are accessed is called escape functions. There are 
two types of escape functions. Output escape functions, implemented by 
ZOESC, provide access to special features of the graphics display device. 
ZIESC allows a program to inquire about the capabilities of the device. 
The feature to be accessed is specified by the value of OPCODE. Since the 
value of OPCODE may specify a different function for each device, refer to 
the Device Handlers Manual for the functions supported by a specific 
graphics display device suid the parameters required. If the OPCODE 
specified is not supported by a particular device an error will be returned 
and the call will be ignored. 

Escape functions can be used anywhere in an application program after the 
graphics display has been initialized. Inquiry escape functions may not be 
requested from a device that is being outspooled. 

Escai>e functions bypass the DGL system auid interact with a device directly. 
The DGL system does not keep track of the use made of the escape functions. 
Escape functions may cause the DGL system to lose track of the state of the 
graphics display device. Therefore, they should be used very carefully. 
Because escape functions are by nature device dependent, they should be used 
sparingly in order to preserve the device independence of application 
programs. 
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Chapter 3 

Detailed Description of DGL Subroutines 

SYSTEM-SPECIFIC CALLS 


The following system-specific calls are described in the appropriate system 
supplement: 


ZAINT ZDINT 

ZBINT ZIWS 


ZKINT ZVINT 
ZLINT 


DEFINITION FORMAT 


Each subroutine definition contains the following information: purpose, 
calling sequence, definition of parameters, commentary, and error condi¬ 
tions. The parameters in DGL calls are always arranged so that input para¬ 
meters precede output parameters. Input parameters are defined as being 
parameters passed to the DGL system, whereas output parameters are returned 
from DGL. Output parameters are underlined in the calling sequence for easy 
reference. A parameter is never used as both an input and output parameter. 
DGL will not change the value of any input parameters. 

All integer parameters in DGL are treated as single precision one word in¬ 
tegers and all reals are treated as single precision two word reals. 

DGL does a minimal amount of error reporting. The conditions which can 
cause errors are documented for every subroutine. Some subroutines (e.g., 
ones which initialize devices, inquire information, and change the display 
limits) return an error parameter which indicates whether the operation was 
performed successfully. In the following subroutine descriptions the error 
conditions are listed in the order in which they are tested. 
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ZAEND 


ZAEND 


PURPOSE: To disable the enabled alphanumeric device. 
CALLING SEQUENCE: CALL ZAEND { no parameters } 


ZAEND terminates and disables the alphanumeric device. It transmits any 
required termination sequence to the device and releases all resources being 
used by the device. The device name is set to the default device name (see 
the Device Handlers Manual), the device status is set to 0 (not enabled) and 
the I/O unit descriptor of the device is set to 0. 

ZAEND is the complementary routine to ZAINT. 

If an alphainumeric device is used, ZAEND should be called before the ap¬ 
plication program is terminated. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Alphanumeric device not currently enabled. 

ACTION: Call ignored. A call to ZAINT should be made prior to this 
call. 
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ZALPH 


ZALPH 


PURPOSE: To output a text string to the alphanumeric device. 


CALLING SEQUENCE: CALL ZALPH ( NCHARS, STRING ) 


NCHARS [ INTEGER; Input ] 

The number of characters from STRING to be output to 
the alphanumeric device. (1 <= NCHARS <= 132). 

STRING [ INTEGER; Array; Input ] 

The text string to be output in Packed ASCII format. 

ZALPH allows the application program to send non-graphics text and data to 
the enabled alphanumeric device. This call can be used to send prompts, 
give status, or print error messages. 

Characters 1 through NCHARS in STRING are sent to the alphanumeric device. 
If NCHARS is less than 1 or greater than 132, the call is ignored. 

Some devices can display only N characters, where N<132. If an application 
prograim attempts to output an NCHARS n\imber of characters, where NCHARS is 
greater than N, only the first N characters of array STRING will be dis¬ 
played. A program can use the subroutine ZIWS to inquire the maiximum number 
of characters that can be output on each line of the alphanumeric device. 
ZIWS can also be used to determine the maximum number of lines viewable at 
any one time on the alphanumeric device. 

A carriage-return line-feed (CRLF) is normally appended to the end of STRING 
when it is sent to the device. To supress the CRLF, an underscore must be 
the last character in STRING. The underscore will not be displayed but must 
be included in the character count, NCHARS. If NCHARS is greater than the 
number of characters a device can display and an underscore is the last 
character in the string, the underscore will be ignored and CRLF will be ap¬ 
pended to the string when it is sent to the device. 

STRING must be dimensioned large enough to contain the number of characters 
defined by NCHARS. 
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ZALPH insures that the picture is current before any output is sent to the 
alphanumeric device. 

Before ZALPH is called the alphanumeric device must be enabled for output 
with a call to ZAINT. It is disabled with a call to ZAEND. 

If the alphanumeric device is physically the ssime device as the graphics 
display device, there are some restrictions as to what should be passed in 
STRING. Any device commands which are sent to the alphainumeric device that 
affect the graphics display could destroy the integrity of the DGL system by 
putting the device in an unknown state. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The alphanumeric device is not currently enabled. 

ACTION: Call ignored. 

3) NCHARS < 1 or NCHARS > 132. 

ACTION: Call ignored. 

k) NCHARS > Maximum number of characters which can be displayed at one 
time. 

ACTION: First N characters will be displayed, where N = maximum number 
of characters that can be displayed at once. 



ZASPK 


ZASPK 


PURPOSE: To redefine the aspect ratio of the virtual coordinate system. 


CALLING SEQUENCE: CALL ZASPK ( XSIZE, YSIZE ) 


XSIZE [ REAL; Input ] 

The width of the virtual coordinate system in dimen¬ 
sionless units. ( XSIZE >0.0 ) 

YSIZE [ REAL; Input ] 

The height of the virtual coordinate system in dimen¬ 
sionless units. ( YSIZE >0.0 ) 


ZASPK sets the aspect ratio of the virtual coordinate system, and hence the 
view surface, to be YSIZE divided by XSIZE. A ratio of 1.0 defines a square 
virtual coordinate system, a ratio greater than 1.0 specifies it to be 
higher than it is wide; and a ratio less than 1.0 specifies it to be wider 
than it is high. Since XSIZE and YSIZE are used to form a ratio, they may 
be expressed in any units as long as they are the same iinits. 

DGL calculates the range of the coordinates of the virtual coordinate system 
based on the value of the aspect ratio. The coordinates of the longer axis 
are always set to range from 0.0 to 1.0 and those of the shorter axis from 
0.0 to a value that achieves the specified aspect ratio. 21ASPK redefines 
the limits of the virtual coordinate system as shown in Table 3"1- 

Table 3-1. Aspect Ratio 


ASPECT RATIO (AR) 

X LIMITS 

Y LIMITS 

AR<1.0 

( 0.0, 1.0 ) 

( 0.0, 1.0*AR ) 

AR=1.0 

( 0.0, 1.0 ) 

( 0.0, 1.0 ) 

AR>1.0 

( 0.0, 1.0/AR ) 

( 0.0, 1.0 ) 
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ZASPK 


When a call to ZASPK is made, the DGL system sets the vieiiport equal to the 
limits of the virtual coordinate system. If the viewport is reset with a 
call to ZVIEW, the viewport limits must be within the X and Y limits of the 
virtual coordinate system. A program could display am image on the entire 
logical display surface in the following manner: 

INTEGER IDUMMY,IERR 
REAL ASPK(2) 


CALL ZIWS (254,0,2,IDUMMY,ASPK,IERR) 
CALL ZASPK (1.0,ASPK(2)) 


The initial value of the aspect ratio is 1.0, setting the virtual coordinate 
system to be a square. This square is mapped to the largest inscribed 
square on any display surface, so that the viewable area is maximized. As a 
result, the initial virtual coordinate system limits range from 0.0 to 1.0 
in both the X and Y directions. A program can access the largest inscribed 
rectangle on the logical display surface by modifying the value of the 
aspect ratio. The exact placement of the rectangle on the logical display 
surface is device dependent, but is normally centered on the CRT and jus¬ 
tified in the lower left-hand comer of the plotter (see the Debtee Handlers 
Manual ). 

The starting position is not altered by this call. Since this call 
redefines the viewing transformation, the starting position may no longer 
represent the last world coordinate position. A call to ZMOVE should there¬ 
fore be made after this call to update the starting position. 

If the logical locator device is associated with the saine physical device as 
the graphics display, then a call to ZASPK will implicitly set the logical 
locator limits equal to the new limits of the virtual coordinate system. 

Since the window is not affected by the ZASPK call, distortion may result in 
the window to viewport mapping if the window does not have the same aspect 
ratio as the virtual coordinate system (see ZWIND). 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) XSIZE or YSIZE is less than or equal to zero. 

ACTION: Call ignored. 


* Inquire the aspect ratio 

* of the logical limits. 

* Set the aspect ratio. 
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ZBEGN 


PURPOSE; Initialize the DGL system. 

CALLING SEQUENCE: CALL ZBEGN < no parameters ) 


ZBEGN initializes the DGL system. It must be the first DGL call made by the 
application program. Any call other them ZBEGN which is made while the sys¬ 
tem is not initialized will be ignored. ZBEGN performs the following 
operations: 

o Sets the timing mode to system buffering mode. 

o Sets the aspect ratio of the view surface to 1.0. 

o Sets the virtual coordinate auid viewport limits to rEUige from 
0.0 to 1.0 in the X and Y directions. 

o Sets the starting position to (0.0,0.0) in world coordinate 
system units. 

o Sets all attributes equal to their default values. 

The DGL system is terminated with a call to ZEND. 


ERROR CONDITIONS: 

1) The DGL system is already initialized. 
ACTION: Call ignored. 
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ZBEND 


PURPOSE: To disable the enabled button device. 
CALLING SEQUENCE: CALL ZBEND < no parameters } 


ZBEND disables and terminates the button device. It transmits any termina¬ 
tion sequence required by the device and releases all resources being used 
by the device. The device name is set to the default device name (see the 
Device Handlers Manual) ^ the device status is set to 0 (not enabled) and the 
I/O unit descriptor of the device is set to 0. 

ZBEND is the complementary routine to ZBINT. 

If the button device is used, ZBEND should be called before the application 
program is terminated. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Button device not currently enabled. 

ACTION: Call ignored. 
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ZBMOD 


ZBMOD 


PURPOSE: To select the timing mode for graphics output. 


CALLING SEQUENCE: CALL ZBMOD ( OPCODE ) 


OPCODE [ INTEGER; Input ] 

The code which determines the timing mode to be used 
with the graphics display. 

OPCODE = 0 - Immediate visibility mode 

= 1 - System buffering mode 


DGL timing modes are provided to control DGL graphics throughput and picture 
update timing. Picture update timing refers to the immediacy of visual 
changes to the graphics display surface. Regardless of the timing mode 
used, the same final picture is sent to the graphics display. Z^OD only 
controls when a picture appears on the graphics display, not what appears. 


The DGL system supports two timing modes: 


Immediate visibility mode 


Requested picture changes will be sent to the graphics display device 
before control is returned to the calling program. Due to operating 
system delays there may be a delay before the picture changes are 
visible on the graphics display device. 

The immediate visibility mode is less efficient than the system buff¬ 
ering mode. It should only be used in those applications that require 
picture changes to take place as soon as they are defined, even if the 
finished picture takes longer to create. When changing the timing 
mode to immediate visibility mode the picture is made current. 
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System buffering mode 

Requested picture changes will be buffered by the DGL system. This 
means that graphic output will not be immediately sent to the display 
device. This allows the DGL system to send several graphics commands 
to the graphics display device in one data transfer, therefore, reduc¬ 
ing the number of transfers. System buffering is the initial timing 
mode. 


The following routines implicitly make the picture current: 

ZALPH, ZBUTN, ZKYBD, ZSLOC, ZSVAL, ZWLOC, ZVATAL, ZIESC, ZDEND, 
ZAINT, ZBINT, ZKINT, ZLINT and ZVINT. 


An alternative to immediate visibility that will solve many application 
needs is the use of system buffering together with the ZMCUR call. With 
this method, an application program places graphics commands into the output 
buffer and flushes the buffer (see ZMCUR) only at times when the picture 
must be fully displayed. 

A call to ZMCUR can be made at any time within an application prograim to in¬ 
sure that the image is fully defined. ^CUR flushes the output buffer but 
does not modify the timing mode. 

Before performing any non-DGL input or output such as a FORTRAN, READ or 
WRITE, the DGL buffer must be empty. If the buffer is not flushed (via im¬ 
mediate visibility or ZMCUR) prior to a non-DGL I/O call, the resulting im¬ 
age may contain some "garbage" such as escape functions or invalid graphics 
data. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Invalid OPCODE specified. 

ACTION: Call ignored. 
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ZBUTN 


PURPOSE: To return a button value from the enabled button device. 

CALLING SEQUENCE: CALL ZBUTN ( ECHO, BUTTON ) 

ECHO [ INTEGER; Input ] 

The type of input echoing. Possible values are: 

ECHO =0 - No echoing 

= 1 to 255 ■ Echo on the button device 

BUTTON [ INTEGER; Output] 

The integer button value returned by the button device 
in the range 0 to 255 • 


ZBUTN waits for a button to be selected on the currently enabled button- 
device. When a button is selected, that button's value is returned in 
BUTTON. 

ZBUTN normally returns a positive integer from 1 to 255 as a function of the 
button or key selected. A zero is returned if an invalid button is ac¬ 
tivated on the button device. The number of buttons supported by a button 
device is device dependent. The correlation between the buttons or keys 
supported on a device and the value returned in BUTTON is also 
device dependent. 

The number of echoes supported on a button device and the correlation be¬ 
tween ECHO and the type of echoing performed is device dependent. Most but¬ 
ton devices support at least one type of echo. Possible echoes are turning 
on a light, beeping, or displaying the button activated. Refer to the 
Device Handlers Manual to determine the number and tjrpe of echoing performed 
by a specific button device. If ECHO is larger than the number of echoes 
supported by the enabled button device, then the call will be treated as if 
ECHO = 1. 

ZBUTN implicitly makes the picture current before requesting input from the 
button device. 

The button device should be enabled before ZBUTN is called (see ZBINT). If 
the button device is not enabled, the call will be ignored. The button 
device is terminated with a call to ZBEND. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The logical button device is not enabled. 

ACTION: Call ignored. 

3) ECHO is out of range. 

ACTION: Treated as if ECHO = 1. 

U) The button activated is out of range. 

ACTION: VALUE set to 0. 
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ZCOLM 


PURPOSE: To choose the color model. 


CALLING SEQUENCE: CALL ZCOLM ( MODEL ) 

MODEL [ INTEGER; Input ] 

The color model DGL will use to interpret subsequent 
changes to or inquires of entries in the color table. 

MODEL = 1 - The RGB (Red-Green-Blue) color cube; the 
default model. 

= 2 - The HSL (Hue-Saturation-Luminosity) color 
cylinder. 


The RGB physical model (see Figure 2-5) is a color cube with the primary ad¬ 
ditive colors, red, green and blue, as its axes. With this model, a call to 
ZDCOL specifies a point within the color cube that has a red intensity value 
(X coordinate), a green intensity value (Y coordinate) and a blue intensity 
value (Z coordinate). Each value rauiges from zero (no intensity) to one. 

The HSL perceptual model (see Figure 2-6) is a color cylinder in ^ich: 

o The angle about the axis of the cylinder, in fractions of a circle, 
is the hue (red is at 0, green is at 1/3 and blue is at 2/3). 

o The radius is the saturation -- ranging from white through grey to 

black along the center axis (S=0) to saturated hues, with no ap¬ 
parent whiteness, at the cylinder's surface (S=l). 

o The height along the center axis is the luminosity (the intensity or 

brightness per unit area); black is at the bottom of the cylinder 

(L=0), and the brightest colors are at the top of the cylinder (L=0) 
with white at the center top. 

Hue (Angle), saturation (radius), and luminosity (height) all range from 
zero to one. Using this model, a call to ZDCOL specifies a point within the 
color cylinder that has a hue value, a saturation value, and a Ivuninosity 
value. 
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When a call to ZCOLM switches color models, parameter values in subsequent 
calls to ZDCOL then refer to the new model. Switching models does not af¬ 
fect color definitions that were previously made using another model. Note 
that when the value of a color table entry is inquired, it is returned in 
the current model, which may not be the model in which it was originally 
specified. 

Not all color specifications can be displayed on every graphics device, 
since the devices which DGL supports differ in their capabilities. If a 
color specification is not available on a device, DGL will use the closest 
available color. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The value of MODEL is not 1 or 2. 

ACTION: Call ignored. 
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ZCOLR 


PURPOSE: To set the color attribute for all primitives except polygon inte¬ 
rior fill. 


CALLING SEQUENCE: CALL ZCOLR-( COLOR ) 


COLOR [ INTEGER; Input ] 

Desired color to he applied to all primitive output ex¬ 
cept for polygon interior fill. COLOR is the index to 
an entry in a device-dependent color table. 

(0 < = COLOR < = 32767 ) 

ZCOLR chooses the color index to be used for the following primitives: 

o Lines 
o Polylines 
o Graphics text 
o Markers 

o Polygon set edges 

The user chooses the color entry to be used for polygon interiors using 
ZPICL. 

Every graphics display device handler in DGL has its own default color 
table. The size of the color table will vary with the device. Every color 
table has at least one entry at index 1. Display devices for which there is 
a background color have an entry at index 0 which is the background color. 
Color 1 is the default color set at DGL initialization and display in¬ 
itialization for all primitives. 

The user who does not wish to use the default color 1 may choose other 
entries in the color table to be used instead. Any entry in the color table 
may be chosen by ZCOLR. If ZCOLR specifies Color 0, the background color» 
results will be device dependent. For example, on plotters, the pen will be 
put away. On some raster displays, lines will be drawn in the background 
color allowing the user to erase existing primitives by drawing over them. 

It is possible to define an entry in a device color table which the device 
is not capable of displaying. When such an entry is chosen using ZCOLR, DGL 
attempts to match the requested color with the closest color of which the 
device is capable. The resulting color may duplicate the color of some 
other entry in the table. 
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On some devices, the ability of the device to display a color will depend on 
the type of primitive being displayed. This will frequently happen on color 
displays which are capable of filling polygon interiors in a wide range of 
colors but which have a narrow selection for all other primitives. In this 
case, line color, for example, may only approximate the color of the entry 
selected by ZCOLR while polygon set interior color may be much closer to the 
color selected with ZPICL. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) The value of COLOR is outside the range of the system (0 to 32767). 
ACTION: Color index 1 is used. 

U) The value of COLOR is outside the range supported by the graphic display 
device. 

ACTION: Color index 1 is used. 
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PURPOSE: Sets the character size attribute for hardware text. 


CALLING SEQUENCE: CALL ZCSIZ ( WIDTH, HEIGHT ) 


WIDTH 


[ REAL; Input ] 

Requested hardware character cell width in world coor¬ 
dinate luiits. 


HEIGHT 


[ REAL; Input ] 

Requested hardware character cell height in world coor¬ 
dinate units. 


ZCSIZ sets the character size for subsequently output graphics text. WIDTH 
and HEIGHT specify the world coordinate size of a character cell. 
Therefore, the actual physical size of the characters output is determined 
by applying the current viewing transformations to the world coordinate 
units specification. Note that a consequence of this is that changing the 

window specification (or other viewing components) can alter the apparent 

size of characters on the graphics display surface. 

The actual character size used is device dependent since not all devices 
support continuously variable character sizes. If the actual character cell 
size requested is not available on the graphics display, then the "smaller 
best fit" size available will be used. The smaller-best-fit character size 
is defined as: 

o The size of the largest character whose cell height is less than or 

equal to the requested height and whose cell width is less than or 

equal to the requested width, or 

o The smallest available size, if the size requested is smaller than 
all available sizes. 

ZIACS can be used to inquire about the actual character size that will be 
used by the graphics display device without setting the character size 
attribute. 

ZIWS can be used to inquire the actual character size that is set by a call 
to ZCSIZ. 
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The character size attribute has no effect on alphanumeric text output using 
ZALPH. 

The default character size (set by ZDINT and ZBEGN) is determined as 
follows: 

1. Height = .05 X (current height of the world coordinate system). 

2. Width = .035 X (current width of the world coordinate system). 

3. The "smaller best fit" rule is then applied. 

If a change is made to the viewing transformation (by ZWIND, ZVIEW, ZDLIM, 
or ZASPK), the value of the character size attribute will not be chsuiged, 
but the actual size of the characters generated may be modified. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Graphics display not currently enabled. 

ACTION: Call ignored. 
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ZDCOL 


PURPOSE: To redefine an entry in the color table. 


CALLING SEQUENCE: CALL 2DC0L ( COLOR,COLPl,C0LP2,C0LP3 ) 


COLOR [ INTEGER; Input ] 

The entry in the color table which is to be 
redefined. (0 <= COLOR <= 3276?) 


COLPl,COLP2,COLP3 [ REAL; Input ] 

New color model values for the entry selected by 
COLOR. (0.0 <= COLPl,COLP2,COLP3 <= 1.0) 


Every graphics display device hauidler in DGL has its own default color 
table. Every default color table has at least an entry at index 1 and dis¬ 
play devices for which there is a background color have an entry at index 0. 
Color 1 is the default color for all primitives and Color 0 is the 
background color of the display device. The other entries in the default 
color table are usually selected to match the basic colors which may be dis¬ 
played on the device. 

The color model parameters set by ZDCOL, and the current color model set by 
ZCOLM, define a new color. This color definition can then be chosen by 
calling ZCOLR or ZPICL. Note that ZDCOL is ignored if the graphic output 
device does not permit its color table to be redefined or if color modelling 
capabilities were suspended by replacing color modelling modules with diunmy 
modules ( HP 1000 only ). Call ZIWS to inquire whether the current device 
permits its color table to be redefined. 

If entry redefinition is supported, a new color value for the entry 
specified in parameter COLOR is set according to the values of the para¬ 
meters COLPl, C0LP2, and C0LP3. VJhen the value of a color entry is 
redefined through ZDCOL, any subsequently output primitives which use that 
entry will reflect the newly defined value. The effect of redefinitions on 
previously output primitives is device dependent. On most devices, 
previously output primitives which used the redefined entry will not change 
color. However, on some devices the redefinition may be retroactive. 

The values of COLPl, C0LP2, and C0LP3 are interpreted according to one of 
two color models, RGB (Red-Green-Blue) or HSL (Hue-Saturation-L\aminosity). 
DGL uses the latest model specified in the ZCOLM call, or the default RGB 
model if no call to ZCOLM has been made. See Table 3"2 for an example of 
the RGB sample colors and Table 3“3 for an example of the HSL sample colors. 


3-19 



ZDCOL 


Table 3-2. Sample Colors Using the RGB Color Model 


COLPl 

RED INTENSITY 

C0LP2 

GREEN INTENSITY 

COLP3 

BLUE INTENSITY 

RESULTING COLOR 

0.0 

0.0 

0.0 

Black 

0.5 

0.5 

0.5 

Gray 

1.0 

1.0 

1.0 

White 

1.0 

0.0 

0.0 

Red 

1.0 

1.0 

0.0 

Yellow 

0.0 

1.0 

0.0 

Green 

0.0 

1.0 

1.0 

Cyan 

0.0 

0.0 

1.0 

Blue 

1.0 

0.0 

1.0 

Magenta 


Table 3-3. Sample Colors Using the HSL Color Model 


COLPl 

HUE 

COLP2 

SATURATION 

COLP3 

LUMINOSITY 

RESULTING COLOR 

Any 

Any 

0.0 

Black 

Any 

0.0 

0.5 

Gray 

Any 

0.0 

1.0 

White 

0.0 or 1.0 

1.0 

1.0 

Red 

1/6 = 0.17 

1.0 

1.0 

Yellow 

2/6 = 0.33 

1.0 

1.0 

Green 

3/6 = 0.50 

1.0 

1.0 

Cyan 

U/6 = 0.67 

1.0 

1.0 

Blue 

5/6 = 0.83 

1.0 

1.0 

Magenta 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call Ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) The color table cannot be changed. 

ACTION: Call ignored. 

4) The value of COLOR is outside the range of the system (0 to 32767). 
ACTION: Call ignored. 

5) The value of COLOR is outside the rainge supported by the graphic display 
device handler. 

ACTION: Call ignored. 

6 ) The value of COLPl, C0LP2 or C0LP3 is outside the range 0.0 to 1.0. 
ACTION: Call ignored. 
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ZDEND 


PURPOSE: To disable the enabled graphics display device. 
CALLING SEQUENCE: CALL ZDEND < no parameters } 


ZDEND terminates the device enabled as the graphics display in the work sta¬ 
tion. ZDEND completes all remaining display device operations and disables 
the logical graphics display. It makes the picture current Euid releases all 
resources being used by the device. ZDEND does not send a new-frame-action 
to the graphics display device. The device name is set to the default 
device name (see the Device Handlers Manual)^ the device status is* set to 0 
(not enabled) and the I/O unit descriptor of the device is set to 0. If 
there is an enabled locator which is the same physical device as the 
graphics display device that is being disabled, the locator limits will be 
reset to the default limits. 

The graphics display device should be disabled before the termination of the 
application program. 2U)END is the complementary routine to ZDINT. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to Z6EGN must be made to initialize the 
DGL system. 

2) Logical graphics display not currently enabled. 

ACTION: Call ignored. 
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ZDLIM 


PURPOSE: To define the logical display limits of the graphics display. 


CALLING SEQUENCE: CALL ZDLIM ( XMIN, XMAX, YMIN, YMAX, lERR ) 


XMIN [ REAL; Input ] 

The left side of the logical display limits is offset 
from the origin of the physical graphics display device 
(distance in millimeters). 

XMAX [ REAL; Input ] 

The right side of the logical display limits is offset 
from the origin of the physical graphics display device 
(distauice in millimeters). 

YMIN [ REAL; Input ] 

The bottom of the logical display limits is offset from 
the origin of the physical graphics display device 

(distance in millimeters). 

YMAX [ REAL; Input ] 

The top of the logical display limits is offset from 

the origin of the physical graphics display device 

(distance in millimeters). 

lERR [ INTEGER; Output ] 

Return code indicating Aether (XMIN,YMIN) and 

(XMAX,YMAX) are within the physical display limits. 

lERR = 0 (XMIN,YMIN) and (XMAX,YMAX) are within the 
physical display limits. 

= 1 XMIN >= XMAX or YMIN >= YMAX. Call ignored. 

= 2 (XMIN,YMIN) or (XMAX,YMAX) is outside the 
physical display limits. Call ignored. 
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ZDLIM allows an application program to specify the region of the display 
surface where the image will be displayed. This region is called the logi¬ 
cal display surface. Upon display device initialization, the DGL system 
sets the logical display limits to be equal to a device-dependent portion of 
the specified physical device. By changing the logical display limits, suiy 
portion of the physical graphics display can be addressed. 

The pairs (XMIN,YNIN) and (XMAX,YMAX) define the comer points of the new 
logical display limits in terms of millimeters offset from the origin of the 
physical display. The exact position of the physical display origin is 
device dependent. (Refer to the Device Handlers Umual). 

ZDLIM sets the view surface to be the maximiun rectangle within the logical 
display limits having the current aspect ratio of the virtual coordinate 
system. ZDLIM does not effect the virtual coordinate system limits, but it 
may reset the view surface limits; therefore, it may have the effect of 
scaling and translation. A call to ZDLIM also sets the locator echo posi¬ 
tion to its default value, the center of the world coordinate system. This 
applies in all cases, not just when the display and location are the same 
device. 

The starting position is not altered by this call. Since this call 
redefines the viewing transformation, the starting position may no longer 
represent the last world coordinate position. A call to ZMOVE, ZPOLY, 
ZPGDD, or ZPGDI should therefore be made after this call to update the 
starting position. 

If the logical display and logical locator are associated with the same 
physical device, a call to ZDLIM will set the logical locator limits equal 
to the new view surface limits. 

ZDLIM should only be called while the graphics display is enabled. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 

3) XMIN >= XMAX or YMIN >=YMAX 

ACTION: lERR set to 1 and the rest of call ignored. 

U) One of the offsets specified is outside of the physical display limits. 
ACTION: lERR set to 2 and the rest of call ignored. 
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PURPOSE: To convert from world coordinates to millimeters on the graphics 
display. 


CALLING SEQUENCE: CALL ZDPMM ( WE, WY, MMX, MMY ) 


WX [ REAL; Input ] 

The X coordinate of a point to be converted from world 
coordinates to millimeters on the graphics display. 

WY t REAL; Input ] 

The Y coordinate of a point to be converted from world 
coordinates to millimeters on the graphics display. 

MMX [REAL; Output ] 

The number of millimeters that the world coordinate 
point (WX,WY) is from the origin along the X axis on 
the graphics display. 

MHY [REAL; Output ] 

The number of millimeters that the world coordinate 
point (WX,WY) is from the origin along the Y axis on 
the graphics display. 

ZDPMM converts the world coordinate point (WX,WY) to the point (MMX,MMY), 
expressed in millimeters from the origin of the graphics display device. 
The location of this origin is device dependent. Refer to the Device 
Handters Mccnual for the position of the origin on a specific device. 

Since the origin of the world coordinate system need not correspond to the 
origin of the physical graphics display, converting the point (0.0,0.0) in 
the world coordinate system may not result in the value (0.0,0.0) offset 
from the physical display device's origin. 

2DPMM accepts any world coordinate point, inside or outside the current win¬ 
dow, and converts to a point offset from the physical display device's 
origin. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 
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PURPOSE: To redefine 
table. 

CALLING SEQUENCE: 

PINDEX 

DENSTY 

ORIENT 

EDGE 


ZDPST 


the polygon style of an entry in the polygon style 


CALL ZDPST ( PINDEX,DENSTY,ORIENT,EDGE ) 


[ INTEGER; Input ] 

The index to the entry in the polygon style table. 
(1 <= PINDEX <= 255 ) 


[ REAL; Input ] 

The desired density of polygon interior fill. 
(-1.0 <= DENSTY <= 1.0) 


[ REAL; Input ] 

The desired orientation of polygon interior fill 
lines. This is the angle (degrees) that the fill 
lines will make with the horizontal aixis of the view 
surface. For a cross-hatched fill, the angular value 
of ORIENT refers to one set of fill lines. The 
second set is perpendicular to the first. 
(-90.0 <= ORIENT <= 90.0) 


[ INTEGER; Input ] 

Specification controlling whether display of the edge 
of the polygon set is permitted. 

EDGE = 0 - No polygon edge display. 

= 1 - Polygon edge display permitted. Display 
of particular edge segments depends on the 
OPCODE parameter in the call that 
generates the polygon set: ZPGDD or ZPGDI. 
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Every graphics device handler in DGL has a default polygon style table. The 
number of entries in the table and their values depend on the graphics 
device. Default definitions are designed to suit each graphics device. The 
first l 6 entries are the same for all devices (see Figure 2-9)* For some 
devices, entries can be added to or deleted from the table before program 
execution. 

VKxen the value of a polygon style entry is redefined through ZDPST, any sub¬ 
sequently output polygon sets which use that entry will reflect the newly 
defined value. The effect of redefinitions on previously output polygons 
sets is device dependent. On most devices, previously output polygon sets 
which used the redefined entry will not chaoige styles. However, on some 
devices the redefinitions may be retroactive. 

DENSTY defines the ratio of filled area (area covered by fill lines) to to¬ 
tal area in the interiors of polygon sets. For completely filled polygon 
sets, make DENSTY = + 1.0; for no fill, make DENSTY = 0.0. Valid densities 
other than + 1.0 and 0.0 describe partially filled interiors. 

A positive density requests parallel fill lines in one direction only. A 
negative density requests cross-hatching with two sets of fill lines at 
right angles. For a given density, the distance between two adjacent paral¬ 
lel lines is greater with cross hatching than in the case of pure parallel 
filling. 

Fill line width is always the thinnest width possible on the graphic display 
device. Also, the distance between fill lines, hence density, does not 
change with a change of scale caused by a viewing transformation. 

The actual percentage of the area covered by lines caui differ from the 
specified density. Density values assume unbroken fill lines. A difference 
will occur when the current interior linestyle, set by ZPILS, calls for gaps 
in the hatch lines. Device-dependent fills produced by ZPGDD may also 
deviate from the requested density. 

Note: Problems with rasterization, device resolution and numerical round¬ 
off may occasionally cause gaps when density = + 1. This most commonly oc¬ 
curs on raster devices when ORIENT is not equal to - 90 . 0 , 0.0, or + 9 O.O 
degrees. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) Dummy polygon routines were loaded. 

ACTION: Call ignored. 

U) The value of PINDEX is outside the remge permitted by DGL (1 to 233)* 
ACTION: Call ignored. 

3) The value of PINDEX is outside the range supported by the graphic dis¬ 
play device. 

ACTION: Call ignored. 

6) The value of DENSTY is outside the range -1.0 to 1.0. 

ACTION: Call ignored. 

7) The value of ORIENT is outside the range -90.0 to 90.0. 

ACTION: Call ignored. 

8) The value of EDGE is not 0 or 1. 

ACTION: Call ignored. 
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ZDRAW 


PURPOSE: To draw a line from the starting position to the world coordinate 
specified. 


CALLING SEQUENCE: CALL ZDRAW ( WX, WY ) 


WX [ REAL; Input ] 

Ending X coordinate of the line to be drawn in the 

world coordinate system. 

WY [ REAL; Input ] 

Ending Y coordinate of the line to be drawn in the 

world coordinate system. 


A line is drawn from the starting position to the world coordinate specified 
by (WX,WY). The starting position is updated to (WX,WY) at the completion 
of this call. 

The DGL system does not perform any software clipping on output primitives. 
If either the starting position or the point (WX,WY) is outside of the cur¬ 
rent view surface, then the resulting picture may not be well defined be¬ 
cause each device handles out-of-range data in a different manner. 

Drawing to the starting position generates the shortest line possible. 
Depending on the nature of the linestyle, nothing may appear on the graphics 
display surface. See ZLSTL for a complete description of how linestyle af¬ 
fects a particular point or vector. 

The primitive attributes of linestyle, color, highlighting and linewidth ap¬ 
ply to lines drawn using ZDRAW. However, the lines will appear with these 
attributes only if the graphics device is capable of applying them to lines. 
Check the device Handtevs Manual for the exact capabilities of the display 
device used to determine the effect of all primitive attributes. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 
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ZEND 


PURPOSE: To terminate the DGL system. 


CALLING SEQUENCE: CALL ZEND { no parameters ) 


ZEND terminates the DGL system. Temination includes making the picture 
current as well as disabling and terminating all currently enabled devices. 
ZEND should be the last DGL call in an application program. 

ERROR CONDITIONS: 


1) The DGL system is not initialized. 
ACTION: Call ignored. 
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PURPOSE: Sets the highlighting attribute for subsequently output 
primitives. 


CALLING SEQUENCE: 

BLIGHT 


CALL ZHIGH ( BLIGHT 

[ INTEGER; Input ] 
Highlighting value. 


) 

(1 <= BLIGHT <= 255) 


A call to 2miGH allows an application program to specify the value of the 
highlighting attribute. Highlighting is a means of emphasizing portions of 
the displayed image. Highlighting is not performed when the highlighting 
attribute equals 1 (the initial value). A device may perform highlighting 
by blinking or intensifying subsequently generated output primitives. 

The type of highlighting available is device dependent. The mapping between 
the values of BLIGHT and the supported highlighting on a device is also 
device dependent. Highlighting of a polygon set affects both the interior 
and exterior of the set. 

If the requested highlighting is not available on the graphics display 
device, then the highlighting attribute will be set equal to the initial 
value of 1. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) Graphics display not currently enabled. 

ACTION: Call ignored. 

3) The highlighting attribute specified by BLIGHT is not in the valid reuige 
of 1 to 255. 

ACTION: Graphics primitives will be output using highlight 1. 

U) The highlighting attribute specified by BLIGHT is not supported by the 
graphics display. 

ACTION: Graphics primitives will be output using highlight 1. 
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PURPOSE: Given a desired character size, it returns the actual character 
size that will be used by the graphics display. 

CALLING SEQUENCE: CALL ZIACS ( DWIDE, DHIGH, AWIDE , AHIGH ) 

DWIDE [ REAL; Input ] 

Requested character cell width in world coordinate units. 

DHIGH [ REAL; Input ] 

Requested character cell height in world coordinate 
units. 

AWIDE [ REAL; Output ] 

Actual width of the character cell, expressed in world 
coordinate units, which will be used to display graphics 
text. 

AHIGH [ REAL; Output ] 

Actual height of the character cell, expressed in world 
coordinate units, which will be used to display graphics 
text. 

Given a desired character size, ZIACS returns the actual character size that 
will be used by the graphics display without setting the character size at¬ 
tribute. The actual character size used is device dependent since not all 
devices support continuous character sizes. If the desired character cell 
size requested is not available on the graphics display device, then the 
"smaller best fit" size available will be returned. The smaller best fit 
character size is defined to be: 

A) The size vdiose cell height is <= the desired height and whose 
cell width is <= the desired width. 

B) If the size requested is smaller than all available sizes then 
the smallest available size will be used. 

ZCSIZ is used to set the character size attribute. 

ERROR CONDITIONS: 

1} The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 
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ZICOL 


PURPOSE; To inquire the color of an entry in the color table. 


CALLING SEQUENCE: CALL ZICOL ( COLOR,COLPl>C0LP2,C0LP3 ) 


COLOR [ INTEGER; Input ] 

The index to the color table entry. 
(0 <= COLOR <= 32767 ) 


COLPl,COLP2,COLP3 [ REAL; Output ] 

Current color model values for the entry assigned to 
COLOR. (0.0 <= COLPl,COLP2,COLP3 <= 1.0) 


ZICOL returns the color value of the indexed entry in the device-dependent 
color table. 

COLPl, COLP2 auid C0LP3 define the color for the table entry indexed by 
COLOR, in accordance with the currently selected color model. If the RGB 
model is currently in use, COLPl gives the red intensity, COLP2 the green 
intensity, and COLP3 the blue intensity. If the HSL model is currently 
used, COLPl gives the hue, COLP2 the saturation and C0LP3 the luminosity. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) The color table cannot be changed. 

ACTION: Call ignored. 

U) The value of COLOR is outside the range of the system (0 to 32767 )^. 
ACTION: Call ignored. 

5) The value of COLOR is outside the range supported by the graphic display 
device. 

ACTION: Call ignored. 
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ZIESC 


PURPOSE: To perform a device-dependent inquiry escape function from the 
graphics display device. 

CALLING SEQUENCE: CALL ZIESC ( OPCODE,ISIZE,RSIZE, ILIST , RLIST , IERR ) 

OPCODE [ INTEGER; Input ] 

The opcode of the device-dependent inquiry escape func¬ 
tion being invoked. The opcodes supported for a given 
device are described in the Devi.ce Handlers Manual. 

[ INTEGER; Input ] 

The number of integer parameters to be returned in ar¬ 
ray ILIST by the escape fvinction. 

[ INTEGER; Input ] 

The number of real parameters to be returned in array 
RLIST by the escape fimction. 

[ INTEGER; Array; Output ] 

The array in vdiich zero or more integer parameters are 
returned by the escape function. If ISIZE equals 0, 
ILIST is a dvunmy parameter. 

[ REAL; Array; Output ] 

The array in which zero or more real parameters are 
returned by the escape function. If RSIZE equals 0, 
RLIST is a dummy parameter. 

[ INTEGER; Output ] 

Code indicating whether the inquiry escape fimction was 
performed. Possible values and their meanings are: 

lERR = 0 Inquiry escape function successfully 

completed. 

= 1 OPCODE not supported by the graphics display 
device. Call ignored. 

= 2 ISIZE is not equal to the number of integer 
parameters to be returned. Call ignored. 

= 3 RSIZE is not equal to the number of real 
parameters to be returned. Call ignored. 

= 4 Graphics display is being outspooled. 

Therefore no input operation can be 

performed. Call ignored. 
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lERR 



ZIESC allows application programs to inquire about special hardware features 
on a graphics display device. The desired inquiry escape function is 
specified by OPCODE. Possible inquiry escape functions may return the 
status or the options supported by a particular graphics display device. 
Refer to the Device Handlers Manual for the inquiry escape fimctions sup¬ 
ported by a specific graphics display device. If the opcode specified is 
not supported by a particular device or if ISIZE or RSIZE are specified in¬ 
correctly an error code will be returned eind the call will be ignored. 

The type of information returned from the graphics display device is deter¬ 
mined by the value of OPCODE. The thouseuids digit of OPCODE specifies the 
number of integer values returned in ILIST; the hundreds digit specifies the 
number of real values returned in RLIST. It is the application program's 
responsibility to insure that ILIST is dimensioned at least as large as 
specified by ISIZE, and that RLIST is dimensioned at least as large as 
specified by RSIZE. If ISIZE or RSIZE are not exactly the size required by 
a particular inquiry escape fmiction, the call will be ignored and an error 
code returned in lERR. 

Inquiry escape functions only apply to graphics display devices. ZIESC can 
be called anywhere in an application program while the graphics display 
device is enabled. ZIESC implicitly makes a picture current before perform¬ 
ing the escape function. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to Z6EGN must be made to initialize DGL. 

2) The logical graphics display is not enabled. 

ACTION: Call ignored. 

3) Graphics display device is being outspooled. 

ACTION: lERR set to U and rest of call ignored. 

4) The specified OPCODE is not supported by the graphics display device. 
ACTION: lERR set to 1 and rest of call ignored. 

5) ISIZE is not equal to the number of integer parameters returned by the 
inquiry escape function. 

ACTION: lERR set to 2 and rest of call ignored. 

6) RSIZE is not equal to the number of real parameters returned by the in¬ 
quiry escape function. 

ACTION: lERR set to 3 and rest of call ignored. 
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PURPOSE: To inquire the polygon style of an entry in the polygon style 
table. 

CALLING SEQUENCE: CALL ZIPST ( PINDEX,DENSTY,ORIENT.EDGE ) 


PINDEX [ INTEGER; Input ] 

The index to the entry in the polygon style table. 
(1 <= PINDEX <= 255 ) 

DENSTY [ REAL; Output ] 

The density of the polygon interior fill. 
(-1.0 <= DENSTY <= 1.0) 

ORIENT [ REAL; Output ] 

The orientation of polygon interior fill. This is the 
angle (degrees) that fill lines make with the horizontal 
axis of the view surface. (- 9 O.O <= ORIENT <= 90*0) 

EDGE [ INTEGER; Output ] 

Specification controlling i4iether display of the edge of 
the polygon set is permitted. 

EDGE = 0 - No polygon edge display. 

= 1 - Polygon edge display permitted. Display 
of particular edge segments depends on a 
parameter within the call (ZPGDD or ZPGDI) 
used to draw the polygon. 


ZIPST returns the device-dependent contents of the polygon style table entry 
specified in PINDEX. 

For a full explanation of polygon style, see 2iDPST in this chapter. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) Dummy polygon routines were loaded. 

ACTION: Call ignored. 

U) The value of PINDEX is outside the range peimitted by DGL (1 to 255)* 
ACTION: Call ignored. 

5) The value of PINDEX is outside the range supported by the graphic dis¬ 
play device. 

ACTION: Call ignored. 
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PURPOSE: To disable the enabled keyboard device. 
CALLING SEQUENCE: CALL ZKEND { no parameters } 


ZKEND terminates and disables the enabled keyboard device. It transmits any 
termination sequence required by the device and releases all resources being 
used by the device. The device name is set to the default device name (see 
the Deoioe Handlers Manual) ^ the device status is set to 0 (not enabled) 
and the I/O unit descriptor of the device is set to 0. 

ZKEND is the complementary routine to ZKINT. 

If a keyboard device is used, ZKEND should be called before the application 
prograun is terminated. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The logical keyboard device is not currently enabled. 

ACTION: Call ignored. 
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ZKYBD 


PURPOSE: To return a string from the enabled keyboard device. 


CALLING SEQUENCE: CALL ZKYBD ( ECHO, MAX, ACTUAL, STRING ) 


ECHO 


MAX 


ACTUAL 


STRING 


[ INTEGER; Input ] 

The level of input echoing. Possible values are: 

ECHO = 0 - No echoing 

= 1 to 255 ■ Echo on the keyboard device 
[ INTEGER; Input ] 

The maximum number of characters to be returned in the 
array, STRING. (1 <= MAX <= 132) 

[ INTEGER; Output ] 

The actual number of characters read from the keyboard 
device and returned in array STRING. 
(0 <= ACTUAL <= MAX) 

[ INTEGER; Array; Output ] 

The array containing the entered character string 
returned to the application program. The string is in 
Packed ASCII format. 


ZKYBD reads text information from the enabled keyboard device. Following 
the call to 2SCYBD, the operator enters text information on the enabled 
keyboard device and activates the keyboard input terminator (e.g., carriage 
return) to complete the call. 

The terminator is not returned in STRING nor is it included in the character 
count returned in ACTUAL. If the terminator is activated without entering 
any text, ACTUAL will be returned as zero. If more than MAX characters are 
entered, only the first MAX characters will be returned to the application 
program. 

The input characters are returned in Packed ASCII format and filled with 
trailing blanks up to MAX characters. 

Note that MAX is the maximum nximber of characters to be returned in the ar¬ 
ray, STRING. If MAX is less than 1 or greater than 132, the call will be 
ignored. It is the calling program's responsibility to insure that STRING 
is dimensioned large enough to hold MAX characters. 
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The niunber of echoes supported by a keyboard device emd the correlation 
between ECHO and the type of echoing performed is device dependent. Most 
keyboard devices support at least one form of echoing. Possible echoes are 
displaying the input as it is entered or beeping. Refer to the Device 
Handlers Manual to determine the number and type of echoes supported by a 
specific keyboard device. If ECHO is not supported by the enabled keyboard 
device, then the call will be treated as if ECHO = 1. 

ZKYBD insures that the picture is current before requesting input from the 
keyboard device. 

The keyboard device should be enabled for input by calling ZKINT before 
ZKYBD. The keyboard device is disabled by calling ZKEND. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The keyboard device is not enabled. 

ACTION: Call ignored 

3) MAX out of rainge. 

ACTION: Call ignored. 

4) ECHO is out of range. 

ACTION: Treated as if ECHO = 1. 
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PURPOSE: To disable the enabled locator device. 


CALLING SEQUENCE: CALL ZLEND < no parameters } 


ZLEND terminates and disables the enabled locator device. It transmits any 
termination sequence required by the device and releases all resources being 
used by the device. The device name is set to the default device name (see 
the Device Handlers Manual), the device status is set to 0 (not enabled) and 
the I/O unit descriptor of the device is set to 0. 

ZLEND is the complementary routine to ZLINT. 

If a locator device is used, ZLEND should be called before the application 
program is terminated. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Logical locator device not currently enabled. 

ACTION: Call ignored. 
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ZLLIM 


PURPOSE: To define the logical locator limits of the locator device. 


CALLING SEQUENCE: CALL ZLLIM ( XMIN, XMAX, YMIN, YMAX, lERR ) 


XMIN [ REAL; Input ] 

The left side of the logical locator limits is offset 
from the origin of the physical locator (distance in 
millimeters). 

XMAX [ REAL; Input ] 

The right side of the logical locator limits is offset 
from the origin of the physical locator (distance in 
millimeters). 

YMIN [ REAL; Input ] 

The bottom of the logical locator limits is offset from 
the origin of the physical locator (distance in 
millimeters). 

YMAX [ REAL; Input ] 

The top of the logical locator limits is offset from 
the origin of the physical locator (distance in 
millimeters). 

lERR [ INTEGER; Output ] 

Return code indicating whether an error occurred. 

lERR = 0 (XMIN,YMIN) and (XMAX.YMAX) are within the 
physical locator limits. 

= 1 XMIN >= XMAX or YMIN >= YMAX Call ignored. 

= 2 (XMIN,YMIN) or (XMAX.YMAX) is outside the 
physical locator limits. Call ignored. 

= 3 The locator and graphics display are mapped 
to be the same physical device, so the logi¬ 
cal locator limits may not be set indepen¬ 
dently but must correspond to the current 
view surface limits. Call ignored. 
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ZLLIM can be used to specify the portion of the physical locator device that 
should be used to perform locator functions. When the logical locator 
device is enabled (via ZLINT) the logical device limits are set to a device¬ 
dependent portion of the physical locator device. With a call to ZLLIM, the 
user can reset the logical locator limits by specifying a new area within 
the physical locator limits. 

The pairs (XMIN,yMIN) and (XMAX,YMAX) define the comer points of the new 
logical locator limits in terms of millimeters offset from the origin of the 
physical locator. The exact position of the physical locator origin is 
device dependent (refer to the DeV-ioe Handlers Manual). 

ZLLIM should only be called while the graphics locator is enabled. ZLLIM 
sets the locator echo position to the default value (see ZLOCP). 

If a logical locator and a logical display are associated with the same 
physical device, then the logical locator limits must be the saune as the 
view surface limits. Specifically, the effects of the association with the 
same physical device are as follows: 

1. The logical locator limits are set to be the same as those of the 
view surface. 

2. Any call which redefines the virtual coordinate system limits will 
also redefine the logical locator limits. These calls are: ZASPK, 
ZDINT, ZDLIM, ZVIEW, ZLINT and ZWIND. 

3 . The logical locator limits cannot be defined by a call to ZLLIM. If 
the user attempts to do so lERR is set equal to 3 and the rest of the 
call is ignored. 

By changing the logical locator limits auiy portion of the locator device can 
be addressed, with the restrictions stated above. 

The logical locator limits always map directly to the view surface, there¬ 
fore, distortion may result in the mapping between the logical locator and 
the display when the logical locator limits and the view surface have dif¬ 
ferent aspect ratios. If this distortion is not desired it can be avoided 
by assuring that the logical locator limits maintain the same aspect ratio 
as that of the view surface. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The graphics locator is not enabled. 

ACTION: Call ignored. 

3) XMIN >= XMAX or YMIN >= YMAX 

ACTION: lERR set to 1 and rest of call ignored. 

4) One of the offsets specified is outside of the physical locator limits. 
ACTION: lERR set to 2 and rest of call ignored. 

5) The logical locator and the logical display are the same physical 
device. The logical locator limits cannot be redefined explicitly (they 
must correspond to the view surface limits). 

ACTION: lERR set to 3 and rest of call ignored. 
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ZLOCP 


PURPOSE: To define the locator echo position on the graphics display. 


CALLING SEQUENCE: 

CALL ZLOCP { WX, 

WY ) 






WX 

[ REAL; Input ] 

X coordinate of 
coordinates. 

the 

locator 

echo 

position 

in 

world 

wy 

[ REAL; Input ] 

Y coordinate of 
coordinates. 

the 

locator 

echo 

position 

in 

world 


ZLOCP allows a progranuner to define the position of the locator echo posi¬ 
tion to he used when echoing on the graphics display device. The locator 
echo position is the starting point for all locator echoes on the graphics 
display. For some of these echoes the locator echo position is also used as 
a fixed reference point. For example, it is used as the anchor point idien a 
rubber band echo is performed. With this echo, the graphics cursor is ini¬ 
tially turned on at the locator echo position. From that time on, the cur¬ 
sor reflects the position of the locator aind a line extends from the locator 
echo position to the locator as it moves around the graphics display. The 
sample locator function, ZSLOC, does not use the locator echo position. 

ZLOCP should only be called while the graphics display and locator are in¬ 
itialized. If the point specified is outside of the window limits, the call 
is ignored. 

The default locator echo position is the center of the window. When the 
locator is initialized, the locator echo position is set to the default 
value. When a call is made which affects the viewing transformations or the 
logical locator limits, the locator echo position is set to the default 
value. The calls which cause this are ZASPK, ZDINT, ZDLIM, ZLINT, ZLLIM, 
ZWIND and ZVIEW. 

Once the locator echo position is set, it retains this value until the next 
call to ZLOCP or until a call is made which resets it to the default value. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 

3) The locator device is not enabled. 

ACTION: Call ignored. 

4) (WX,WY) is outside of the limits of the window. 

ACTION: Call ignored. 
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ZLPMM 


PURPOSE: To convert from world coordinates to millimeters on the locator 
surface. 


CALLING SEQUENCE: CALL ZLPMM ( WX, Wf, MMX, MMY ) 


WX [ REAL; Input ] 

The X coordinate of the point to be converted from world 
coordinates to millimeters on the physical locator. 

WY [ REAL; Input ] 

The y coordinate of the point to be converted from world 
coordinates to millimeters on the physical locator. 

MMX [ REAL; Output ] 

The offset of the world point (WX,WY) in millimeters from 
the origin of the physical locator device. 

MMY [ REAL; Output ] 

The offset of the world point (WX,Wy) in millimeters from 
the origin of the physical locator device. 


ZLBIM converts the world coordinate point (WX,WY) to the point (MMX,MMY), 
expressed in millimeters from the origin of the physical locator device. 
The location of this origin is device dependent. Refer to the Device 
Handlers Manual for the position of the origin on a specific device. 

Since the origin of the world coordinate system need not correspond to the 
origin of the physical locator device, converting the point (0.0,0.0) in the 
world coordinate system may not result in the value (0.0,0.0) offset from 
the physical locator device's origin. 

ZLPMM will take any world coordinate point, inside or outside the current 
window, and convert it to a point offset from the physical locator's origin. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) The graphics locator is not enabled. 

ACTION: Call ignored. 
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ZLSTL 


PURPOSE: To set the llnestyle attribute for all primitives except polygon 
interior fill and markers. 


CALLING SEQUENCE: CALL ZLSTL ( LSTYLE ) 


LSTYLE [ INTEGER; Input ] 

Desired linestyle to be applied to all subsequent out¬ 
put primitives except polygon interior fill and 
markers. LSTYLE is the index to an entry in a device¬ 
dependent linestyle table. (1 <= LSTYLE <= 255) 


Every graphics device handler in DGL has a linestyle table that cannot be 
changed. The size of the linestyle table will vary with the device. Every 
linestyle table has at least an entry at index 1 which specifies solid 
lines. Linestyle 1 is the default linestyle set at DGL initialization auid 
display initialization. 

The user who does not wish to use the default linestyle 1 may choose other 
entries in the linestyle table to be used instead. Refer to the Dev-ioe 
Handlers Manual for more information on supported linestyles. 

ZLSTL chooses the linestyle index to be used for all primitives except 
markers auid polygon interior fill lines. Markers are always drawn with 
solid lines. The user chooses the linestyle for polygon interior fill lines 
using ZPILS. 

A linestyle is a recurring pattern of dots, bleuiks, short line segments and 
long line segments. DGL can draw any linestyle in any of three ways: start- 
adjusted, continuous, or vector-adjusted. However, the capability to draw 
in any or all of these linestyles is device dependent. On some devices, for 
instance, all linestyles are drawn in a continuous manner. 

START-ADJUSTED linestyles always start the drawing cycle at the beginning of 
the vector. Thus if the linestyle starts with a pattern, each vector drawn 
will start with that pattern. Likewise, if the current linestyle starts 
with a space and then a dot, each vector will be drawn starting with a space 
and then a dot. In this case if the vectors are short, they might not ap¬ 
pear at all. 
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CONTINUOUS llnestyles are generated such that the pattern will be started 
with the first vector drawn. Subsequent vectors will be continuations of 
the pattern. Thus, it may take several vectors to complete one cycle of the 
pattern. This t 3 rpe of linestyle is useful for drawing smooth curves, but 
does not necessarily draw either end point of a vector. A side effect of 
this type of linestyle is if a vector is small enough it might be composed 
only of the space between points or dashes in the linestyle. In that case, 
the vector may not appear on the graphics display at all. 

VECTOR-ADJUSTED linestyles treat each vector individually. Individual 
treatment guarantees that a solid component of the dash pattern will be 
generated at both ends of the vector. Thus, the endpoints of each vector 
will be clearly identifiable. This type of linestyle is good for drawing 
rectangles. The integrity of the linestyle will degenerate with very small 
vectors; since some component of the dash pattern must appear at both ends 
of the vector, the entire vector for a short vector will often be drawn as 
solid. 

Figure 2-7 illustrates how one pattern would be displayed using various dif¬ 
ferent linestyle types. 

Note that an entire vector might not be drawn if it is smaller thsm the 
blaink spaces in the selected linestyle. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) The value of LST7LE is outside the rauige permitted by DGL (1 to 255)* 
ACTION: Linestyle 1 is used. 

U) The value of LSTYLE is outside the range supported by the graphic dis¬ 
play device. 

ACTION: Linestyle 1 is used. 
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PURPOSE: Sets the linewidth attribute for all primitives except polygon in¬ 
terior fill and markers. 


CALLING SEQUENCE: CALL ZLWID ( LWIDTH ) 


LWIDTH [ INTEGER; Input ] 

Desired linewidth to be applied to all subsequent out¬ 
put primitives except polygon interior fill and 
markers. LWIDTH is the index to an entry in a device- 
dependent linewidth table. ( 1 <= LWIDTH <= 255 ) 


Every graphics device handler in DGL has a linewidth table that cannot be 
changed. The size of the linewidth table will vary with the device. Every 
linewidth table has at least an entry at index 1 fdiich specifies the thin¬ 
nest linewidth available. Linewidth 1 is the default linewidth set at DGL 
initialization and display initialization. 

The user who does not wish to use the default linewidth 1 may choose other 
entries in the linewidth table to be used instead. For devices that support 
multiple linewidths, the linewidth increases as LWIDTH does until the device 
supported maximum is reached. For exaimple, LWIDTH = 1 specifies the thin¬ 
nest, LWIDTH = 2 specifies the next wider linewidth, auid so on. Refer to 
the Device Handlers Manual for more information on supported linewidths. 

Markers and polygon interior fill are always drawn with the thinnest 
linewidth available. 


ERROR CONDITIONS: 


1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) Graphics display is not enabled. 

ACTION: Call ignored. 

3) LWIDTH not supported by the graphics display. 

ACTION: Linewidth attribute set to 1 (thinnest). 

4) LWIDTH out of range (1-255). 

ACTION: Linewidth attribute set to 1 (thinnest). 
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PURPOSE: To display a marker symbol at the current position. 

CALLING SEQUENCE: CALL ZMARK ( MARKNO ) 

MARKNO [ INTEGER; Input ] 

An integer that identifies a marker, in the range 
1 - 255 • There are I 9 device-independent markers. They 
are: 


1 - . 

7 - rectangle 

13 

- 3 

2 - + 

8 - diamond 

lU 

- U 

3 - * 

9 - rectangle with cross 

15 

- 5 

4 - 0 

10-0 

16 

- 6 

5 - X 

11-1 

17 

- 7 

6 - triangle 

12-2 

18 

- 8 



19 

- 9 

Marker numbers 

20 to 255 are device dependent. 



ZIMARK displays a marker designated by MARKNO centered on the starting posi¬ 
tion. The starting position is left xmchsinged at the completion of this 
call. 

If the marker number (MARKNO) is greater than the number of distinct marker 
symbols supported by the graphic display device, then marker 1 (".") is 
used. Call ZIWS to find out the number of markers available on the graphics 
device. Refer to the Device Handlevs Manual for special markers supported 
by specific devices. Depending on the capabilities of a device, DGL uses 
either hardware or software to generate a marker symbol. Since the DGL sys¬ 
tem does not do software clipping, placing a marker partly or completely 
outside the window limits will produce results that are device dependent. 

The size auid orientation of markers are fixed auid not affected by viewing 
transformations. The size of markers is device dependent and caumot be 
changed. Typically, marker size is the smallest character size available on 
a device. 

Only the attributes of color and highlighting apply to markers. However, 
the markers will appear with the attributes only if the graphics device is 
capable of applying them to markers. Check the Device Handlers Manual for 
the exact capabilities of the display device used to determine the effect of 
all primitive attributes. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to initialize a 
device. 

3) The value of MARKNO is outside the range permitted by DGL (1 to 255)* 
ACTION: Marker 1 (".") is used. 

U) The value of MARKNO is outside the range supported by the graphic dis¬ 
play device. 

ACTION: Marker 1 (".") is used. 
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ZMCUR 


PURPOSE: To make the picture current. 

CALLING SEQUENCE: CALL ZMCUR { no parameters } 


The graphics display surface can be made current at any time with a call to 
ZMCUR. This insures that all previously generated primitives have been sent 
to the graphics display device. Due to operating system delays, all picture 
changes may not have been displayed on the graphics display upon return to 
the calling program. IQICUR is most often used in system buffering mode (see 
ZBMOD) to make sure that all output has been sent to the graphics display 
device when required. 

Before performing any non-DGL input or output, such as a FORTRAN READ or 
WRITE statement to a DGL device, it is essential that all of the previously 
generated output primitives be sent to the device. If immediate visibility 
is the current timing mode, all primitives will be sent to the device before 
completion of the call to generate them, but if system buffering is used, 
ZMCUR should be called before performing any non-DGL I/O. 

When changing the timing mode to immediate visibility, the picture is made 
current. The following routines implicitly make the picture 
current - ZALPH, ZBUTN, ZKYBD, ZSLOC, ZSVAL, ZWLOC, ZWVAL, ZIESC, ZDEND, 
ZAINT, ZBINT, ZKINT, ZLINT and ZVINT. 

A call to ZMCUR can be made at any time within an application program to in¬ 
sure that the image is fully displayed. ZMCUR does not modify the current 
timing mode. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Graphics display not enabled. 

ACTION: Call ignored. 
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ZMOVE 


PURPOSE: To set the starting position to the world coordinate position 
specified. 


CALLING SEQUENCE: CALL ZMOVE ( WX, WY ) 


WX [ REAL; Input ] 

X coordinate of the new starting position in world 

coordinates. 

WY [ REAL; Input ] 

Y coordinate of the new starting position in world 

coordinates. 


ZMOVE specifies a new starting position. It does this by setting the value 
of the starting position to the world coordinate system point specified by 
( WX,WY ). This point will then be the starting position of the next output 
primitive. 

Since the DGL system does not perfozmi software clipping, setting the start¬ 
ing position to a point outside of the current view surface limits will 
produce device-dependent results. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The logical graphics display is not currently enabled. 

ACTION: Call ignored. 
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ZNEWF 


PURPOSE: Performs a new-frame-action on the graphics display. 


CALLING SEQUENCE: CALL ZNEWF < no parameters > 


The DGL system provides the capability to make the picture current and then 
clear the graphics display of all output primitives. This new-frame-action 
has different connotations for each graphics display surface. On CRT 
devices such as graphics terminals, the screen will be erased. Plotters 
with page advance will advance the paper. On devices such as drum plotters 
or fixed page plotters, a call to 23IEWF only makes the picture current. 

The buffered new-frame-action bit on the ZDINT call can affect the timing of 
the clearing of the graphics display (see ZDINT for use of this bit and the 
Deoioe Handters Hanual for its effect on a particular device). 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The logical graphics display is not currently enabled. 

ACTION: Call ignored. 
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PURPOSE: 


To perform a device-dependent output escape function on the 
graphics display device. 


CALLING SEQUENCE: CALL ZOESC ( OPCODE,ISIZE,RSIZE,ILIST,RLIST>IERR ) 


OPCODE 


ISIZE 


RSIZE 


ILIST 


RLIST 


lERR 


[ INTEGER; Input ] 

The opcode of the output escape function to be perform¬ 
ed. The opcodes supported for a given device are 
described in the DeTfice Handlers Manual. 


[ INTEGER; Input ] 

The number of integer parameters required by the selec¬ 
ted output escape function. 

[ INTEGER; Input ] 

The nxunber of real parameters required by the selected 
output escape function. 

[ INTEGER; Array; Input ] 

An array containing an ISIZE number of integer ele¬ 
ments. If ISI2£ = 0, ILIST is a dummy parameter. 

[ REAL; Array; Input ] 

An array containing an RSIZE number of real elements. 
If RSIZE = 0, RLIST is a dummy parameter. 

[ INTEGER; Output ] 

Code indicating vdiether the output escape function was 
performed. Possible values and their meanings are: 


lERR = 0 Output escape fvinction successfully sent to 
the device. 


= 1 OPCODE not supported by the graphics display 
device. Call ignored. 

= 2 ISIZE is not equal to the number of required 
integer parameters. Call ignored. 

= 3 RSIZE is not equal to the number of required 
real parameters. Call ignored. 



ZOESC 


ZOESC allows an application program to access special hardweire features on a 
graphics display device. The desired output escape function is specified by 
OPCODE. Possible functions may change the hardware character set or draw a 
circle using a device's circle generator. Refer to the Device Handlers 
Manual for the output escape functions supported by a specific graphics dis¬ 
play device and the parameters required. If the OPCODE specified is not 
supported by a particular device or if RSIZE or ISIZE are specified incor¬ 
rectly, an error code will be returned and the call will be ignored. 

The type of information sent to the graphics display device is determined by 
the value of OPCODE. The thousands digit of OPCODE specifies the n\imber of 
integer values returned in ILIST; the hundreds digit specifies the number of 
real values returned in RLIST. It is the application program's respon¬ 
sibility to insure that ILIST is dimensioned at least as large as specified 
by ISIZE, and that RLIST is dimensioned at least as large as specified by 
RSIZE. If ISIZE or RSIZE is not exactly the size required by a particular 
output escape function then the call will be ignored and 201 error will be 
returned in lERR. 

Output escape fimctions only apply to graphics display devices. Output es¬ 
cape functions cam be used anywhere in an application program ;diile the 
graphics display device is enabled. Due to the fact that the DGL system 
does not check the parameters passed by ZOESC, the user must insure that the 
data passed to the device is valid. 

The starting position may be altered by a call to ZOESC. Refer to the 
Device Handlers Manual for the effect of various output escape functions on 
a particular device. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) The logical graphics display is not enabled. 

ACTION: Call ignored. 

3) The specified OPCODE is not supported by the graphics display device. 
ACTION: lERR set to 1 and rest of call ignored. 

U) ISIZE is not equal to the required niunber of integer parameters. 

ACTION: lERR set to 2 and rest of call ignored. 

5) RSIZE is not equal to the required niunber of real parameters. 

ACTION: lERR set to 3 and rest of call ignored. 
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PURPOSE: To display a polygon set in a device-dependent 

manner. 

CALLING SEQUENCE: CALL ZPGDD ( NPOINT,XVEC,YVEC,OPCODE ) 


NPOINT [ INTEGER; Input ] 

The number of values in each array: XVEC, YVEC and 
OPCODE. 

XVEC,YVEC [ REAL; Array; Input ] 

XVEC and YVEC are real arrays that sequentially 
specify the vertices of all the members of a polygon 
set. The vertices for the first member polygon must 
be at the start of these arrays, followed by the ver¬ 
tices for the second member polygon, and so on. 

OPCODE t INTEGER; Array; Input ] 

Control values that define member polygons and 
specify which segments of their edges will be 
displayed. 

OPCODE(i) = 0 - Do not display the edge segment from 
the (i-l)th vertex to the ith vertex 
of the polygon set. 

1 - Display the edge segment from the 

(i-l)th vertex to the ith vertex. 

2 - The ith vertex is the first vertex of 

a member polygon. 

No edge segments are displayed if 
EDGE = 0 in the polygon style. 

Note: OPCODE (l) must be equal to 2 otherwise DGL 
will ignore the call. 


ZPGDD draws polygon sets in the current polygon style as accurately as pos¬ 
sible, using the hardware capabilities of the graphics device. ZPGDI should 
be used to request that polygon sets be produced in a dev ice-independent 
manner. Generally, ZPGDD draws polygon sets with greater speed and more 
economical use of memory, and ZPGDI draws them with greater accuracy aind 
xmiformity. 
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Polygon fill capabilities can vary widely between devices. A device may 
have no filling capabilities at all, may be able to perform only solid fill, 
or may be able to fill polygons with different fill densities and at dif¬ 
ferent fill line orientations. Some devices may be able to apply their 
capabilities to single rectauigles only, while some may handle the full range 
of concave and convex polygon sets. ZPGDD tries to match the device 
capabilities to the request. If the device cannot fill the request at all 
(e.g., the device only handles recteingles and the request is for a filled 
complex polygon set), the polygon will not be filled. 

In the case where the polygon style specifies nondisplay of edges, to 
provide some visible output, ZPGDD will outline the polygon using the 
polygon interior fill attributes. However, only those edge segments 
specified as displayable by OPCODE will be drawn. Refer to the DeOice 
Handlers Manual for a description of the polygon capabilities of a par¬ 
ticular device. DGL automatically closes each member polygon with a non- 
visible edge segment if its last vertex does not coincide with its first. 
To display the closing edge segment, the first and last vertices must be 
coincident and OPCODE for the last vertex must equal 1. 

The DGL system does not perform any software clipping on output primitives. 
If any of the points specified in XVEC and YVEC are outside of the current 
view surface, then the resulting picture may not be well defined because 
each device handles out of range data in a different maomer. 

At the completion of this call the starting position is set to the first 
vertex of the last member polygon in the set. 

The attributes of color, polygon interior color, highlighting, linestyle, 
polygon interior linestyle, polygon style and linewidth apply to polygons. 
However, the polygons will appear with these attributes only if the graphics 
device is capable of applying them to polygons. Check the Device Handlers 
Manual for the exact capabilities of the display device used to determine 
the effect of all primitive attributes. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) On the HP 1000, dummy polygon routines were loaded. 

ACTION: Call ignored. 

U) NPOINT is a non-positive integer. 

ACTION: Call ignored. 

5) More vertices are specified in XVEC and YVEC than the current graphic 
display device can hauidle. 

ACTION: The polygon set is outlined. 

6) OPCODE(1) does not equal 2. 

ACTION: Call ignored. 

7) OPCODE(i) (i > 1) does not equal 0, 1, or 2. 

ACTION: The polygon set is drawn but the results are unpredictable. 

8) An interior fill line crosses the edge of the polygon set too meuiy 
times. See the system dependent supplement for a description of ap¬ 
plicable limits and the Device Handlers Manual for the display being 
used. 

ACTION: The fill line is not drawn. 
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PURPOSE: To display 
CALLING SEQUENCE: 

NPOINT 

XVEC.YVEC 


OPCODE 


ZPGDI 


polygon set in a device-independent manner. 
CALL ZPGDI ( NPOINT,XVEC,YVEC,OPCODE ) 


[ INTEGER; Input ] 

The number of values in each array: XVEC, YVEC and 
OPCODE. 

[ REAL; Array; Input ] 

XVEC and YVEC are real arrays that sequentially 
specify the vertices of all the members of a polygon 
set. The vertices for the first member polygon must 
be at the start of these arrays, followed by the ver¬ 
tices for the second member polygon, and so on. 

[ INIEGER; Array; Input ] 

Control values that define member polygons and 
specify vdiich segments of their edges will be 
displayed. 

OPCODE(i) = 0 - Do not display the edge segment from 
the (i-l)th vertex to the ith vertex 
of the polygon set. 

1 - Display the edge segment from the 

(i-l)th vertex to the ith vertex. 

2 - The ith vertex is the first vertex of 

a member polygon. 

No edge segments are displayed if 
EDGE = 0 in the polygon style. 

Note: OPCODE (1) must be equal to 2 otherwise DGL 
will ignore the call. 
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ZPGDI draws polygon sets in a dev ice-independent manner. This is done in 
software unless the device is capable of producing polygon sets in the en¬ 
tire polygon style range described below. ZPGDD draws polygon sets using 
the hardware capabilities of the device. Generally, ZPGDI draws polygon 
sets with greater accuracy and uniformity, and ZPGDD draws them with greater 
si>eed and more economical use of memory. 

DGL may place a limit on the number of polygon vertices which the user may 
specify (see the system dependent supplement). If the number of vertices 
specified is greater than the number that can be filled, the polygon will 
not be filled. In the case where the polygon style specifies nondisplay of 
edges, to provide some visible output, ZPGDI will outline the polygon using 
the polygon interior fill attributes. However, only those edge segments 
specified as displayable by OPCODE will be drawn. 

DGL automatically closes each member polygon with a non-visible edge segment 
if its last vertex does not coincide with its first. To display the closing 
edge segment, the first and last vertices must be coincident and OPCODE for 
last vertex must equal 1. 

The DGL system does not perform any software clipping on output primitives. 
If any of the points specified in XVEC and YVEC are outside of the current 
view surface, then the resulting picture may not be well defined because 
each device handles out of range data in a different manner. 

At the completion of this call, the starting position is set to the first 
vertex of the last member polygon in the set. 

The attributes of color, polygon interior color, highlighting linestyle, 
polygon interior linestyle and linewidth apply to polygon primitives. 
However, the polygons will appear with these attributes only if the graphics 
device is capable of applying them to polygons. Check the Device Handlers 
Manual for the exact capabilities of the display device used to determine 
the effect of all primitive attributes. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to 2S>INT must be made to enable a device. 

3) On the HP 1000, dummy polygon routines were loaded. 

ACTION: Call ignored. 

1») NPOINT is a non-positive integer. 

ACTION: Call ignored. 

5) More vertices were specified in XVEC thaui can be filled. See the sys¬ 
tem dependent supplement for a description of applicable limits. 

ACTION: The polygon set is outlined. 

6) OPCODE(1) does not equal 2. 

ACTION: Call ignored. 

7) OPCODE(i) (i >1) does not equal 0, 1, or 2. 

ACTION: The polygon set is drawn but the results are unpredictable. 

8) An interior fill line crosses the edge of the polygon set too many 
times. See the system dependent supplement for a description of ap¬ 
plicable limits and the Device Handlers Manual for the display being 
used. 

ACTION: The fill line is not drawn. 
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ZPICL 


PURPOSE: To set color attribute for polygon interior fill. 


CALLING SEQUENCE: CALL ZPICL ( COLOR ) 


COLOR [ INTEGER; Input ] 

Desired color for the interior fill of polygon sets. 
COLOR is the index to an entry in a device-dependent 
color table. (0 <= COLOR <= 32767) 


ZPICL sets the color index for the interior fill of subsequent polygon sets. 
ZCOLR sets the color index for all other primitives, including the edges of 
polygon sets. 

Every graphics display device handler in DGL has its own default color 
table. The size of the color table will vary with the device. Every 
default color table has at least one entry at index 1. Display devices for 
tdiich there is a backgroimd color have an entry at index 0 which is the 
background color. Color 1 is the default color set at DGL initialization 
and display initialization for all primitives. 

The user who does not wish to use the default color 1 for polygon interior 
fill may choose other entries in color table to be used instead. Any entry 
in the color table may be chosen by ZPICL. If ZPICL specifies Color 0, the 
background color, results will be device dependent. For example, on plot¬ 
ters, the pen will be put away. On raster displays, lines will be drawn in 
the background color allowing the user to erase existing primitives by draw¬ 
ing over them. 

It is possible to define an entry in a device color table vdiich the device 
is not capable of displaying. When such an entry is chosen using ZPICL, DGL 
attempts to match the requested color with the closest color of which the 
device is capable. The resulting color may duplicate the color of some 
other entry in the table. 

On some devices, the ability of the device to display a color will depend on 
the type of primitive being displayed. This will frequently happen on color 
displays which are capable of filling polygon interiors in a wide range of 
colors but which have a narrow selection for all other primitives. In this 
case, line color, for exaunple, may only approximate the color of the entry 
selected by ZCOLR while polygon set interior color may be much closer to the 
color selected with ZPICL 
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ERROR CONDITIONS: 

1) The DGL system Is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) On the HP 1000, diimmy polygon routines were loaded. 

ACTION: Call ignored. 

4) The value of COLOR is outside the range of the system (0 to 3276?)• 
ACTION: Color index 1 is used. 

5) The value of COLOR is outside the range supported by the graphic display 
device. 

ACTION: Color index 1 is used. 
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ZPILS 


PURPOSE: To set the linestyle attribute for polygon interior fill. 


CALLING SEQUENCE: CALL ZPILS ( LSTYLE ) 


LSTYLE ( INTEGER; Input ] 

Desired linestyle for the interior fill lines of 
polygon sets. LSTYLE is the index to an entry in a 
device-dependent linestyle table. (0 <= LSTYLE <= 255) 


Every graphics device handler in DGL has a linestyle table that cannot be 
changed. The size of the linestyle table will vary with the device. Every 
linestyle table has at least an entry at index 1 which specifies solid 
lines. Linestyle 1 is the default linestyle set at DGL and display in¬ 
itialization for all primitives. 

The user who does not wish to use the default linestyle 1 may choose other 
entries in the linestyle table to be used instead. Refer to the Device 
Handler's Manual for more information on supported linestyles. 

ZPILS sets the linestyle index for interior fill lines of subsequent polygon 
sets. ZLSTL chooses the linestyle index for all other primitives except 
markers, including the edges of polygon sets. 

A linestyle is a recurring pattern of dots, blanks, short line segments euid 
long line segments. DGL can draw any linestyle in any of three ways: 
start-adjusted, continuous or vector-adjusted. However, the capability to 
draw in any or all of these linestyles is device dependent. On some 
devices, for instance, all linestyles are drawn in a continuous manner. 

START-ADJUSTED linestyles always start the drawing cycle at the beginning of 
the vector. Thus, if the linestyle starts with a pattern, each vector drawn 
will start with that pattern. Likewise, if the current linestyle starts 
with a space auid then a dot, each vector will be drawn starting with a space 
and then a dot. In this case if the vectors are short, they might not ap¬ 
pear at all. 
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CONTINUOUS linestyles are generated such that the pattern will be started 
with the first vector drawn. Subsequent vectors will be continuations of 
the pattern. Thus, it may take several vectors to complete one cycle of the 
patteni. This type of linestyle is useful for drawing smooth curved but 
does not necessarily draw either end point of a vector. A side effect of 
this type of linestyle is if a vector is small enough it might be composed 
only of the space between points or dashes in the linestyle. In that case, 
the vector may not appear on the graphics display at all. 

VECTOR-ADJUSTED linestyles treat each vector individually. Individual 
treatment guarantees that a solid component of the dash pattern will be 
generated at both ends of the vector. Thus, the endpoints of each vector 
will be clearly identifiable. This t 3 rpe of linestyle is good for drawing 
rectangles. The integrity of the linestyle will degenerate with very small 
vectors; since some component of the dash pattern must appear at both ends 
of the vector, the entire vector will often be drawn as solid. 

Figure 2-7 illustrates how one pattern would be displayed using various dif¬ 
ferent linestyle types. 

Note that an entire vector might not be drawn if it is smaller than the 
blank spaces in the selected linestyle. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) On the HP 1000, dummy polygon routines were loaded. 

ACTION: Call ignored. 

U) The value of LSTYLE is outside the range permitted by DGL (1 to 255)* 
ACTION: Linestyle index 1 is used. 

5) The value of LSTYLE is outside the rainge supported by the graphic dis¬ 
play device. ACTION: Linestyle index 1 is used. 
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PURPOSE: To draw a connected line sequence starting at the specified point. 

CALLING SEQUENCE: CALL ZPOLY ( NPTS, XVEC, YVEC ) 

NPTS [ INTEGER; Input ] 

The number of points in the connected line sequence. 
NPTS = (number of lines) + 1. 

XVEC [ REAL; Array; Input ] 

The array of X coordinate values for each line in the 
sequence. 

YVEC [ REAL; Array; Input] 

The array of Y coordinate values for each line in the 
sequence. 


The subroutine ZPOLY provides the capability to draw a series of connected 
lines starting at the specified point. A complete object can be drawn by 
making one call to this subroutine. This call first sets the starting posi¬ 
tion to be the first elements in the XVEC,YVEC arrays. The line sequence 
begins at this point and is drawn to the second element in each array, then 
to the third amd continues until NPTS-1 lines are drawn. 

This call is equivalent to the following sequence of calls: 

CALL ZMOVE (XVEC(l),YVEC(1)) 

CALL ZDRAW (XVEC(2),YVEC(2)) 

CALL ZDRAW (XVEC(3),YVEC(3)) 

CALL ZDRAW (XVEC(NPTS),YVEC(NPTS)) 

The DGL system does not perform software clipping on output primitives. If 
any of the points specified in XVEC and YVEC are outside of the current view 
surface limits, the resulting image will be device dependent. 

The starting position is set to (XVEC(NPTS), YVEC(NPTS)), at the completion 
of this call. 


3-68 



ZPOLY 


Specifying only one element, or NPTS equal to 1, causes a move to be made to 
the world coordinate point {XVEC(l),yVEC(l)). 

It is the application program's responsibility to insure that XVEC, and YVEC 
are all dimensioned to at least NPTS and that at least NPTS values are con¬ 
tained in each array. 

Depending on the nature of the current linestyle nothing may appear on the 
graphics display. See ZLSTL for a complete description of how linestyle af¬ 
fects a particular point or vector. 

The primitive attributes of color, highlighting, linestyle, auid linewidth 
apply to polylines. However, the polyline will appear with these attributes 
only if the graphics device is capable of applying them to polylines. Check 
the Device Handlers Manual for the exact capabilities of the display device 
used to determine the effect of all primitive attributes. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Graphics display is not enabled. 

ACTION: Call ignored. 

3) NPTS <= 0 

ACTION: Call ignored, 
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ZPSTL 


Purpose: To set the polygon style for polygon sets. 

CALLING SEQUENCE: CALL ZPSTL ( PINDEX ) 


PINDEX [ INTEGER; Input ] 

Desired style for polygon sets. PINDEX is an index 
into a device-dependent polygon style table. 

( 1 <= PINDEX <= 255 ) 

Every graphics device haindler in DGL has a polygon style table. ZPSTL sets 
the style attribute for subsequent polygon sets. The first I 6 styles are 
the same for all devices (see Figure 2-9). See ZDPST for an explauiation of 
polygon style. 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a 
device. 

3) On the HP 1000, dvunmy polygon routines were loaded. 

ACTION: Call ignored. 

U) The value of PINDEX is outside the range permitted by DGL (1 to 255). 
ACTION: Polygon style 1 is used. 

5) The value of PINDEX is outside the range supported by the graphic dis¬ 
play device. 

ACTION: Polygon style 1 is used. 
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PURPOSE: To sample the enabled locator device and return the locator point 
without waiting for operator response. 

CALLING SEQUENCE: CALL ZSLOC ( ECHO, WX, WY ) 


ECHO [ INTEGER; Input ] 

The level of input echoing. Legal values are: 

ECHO = 0 - No echo. 

= 1 to 255 " Echo on the locator device. 

WX, WY I REAL; Output ] 

The world coordinate point returned from the enabled 
locator. This point may be outside the current logical 
locator limits. 


ZSLOC returns the current world coordinate value of the locator in (WX,WY) 
without waiting for an operator response. To wait for an operator response 
before returning the value of the locator, see ZWLOC. ZSLOC implicitly 
makes the picture current before sampling the locator. The locator device 
should be enabled prior to calls to ZSLOC (see ZLINT). The locator device 
is disabled by calling ZLEND. 

The number of echoes supported by a locator device and the correlation be¬ 
tween ECHO and the type of echoing performed is device dependent. Most 
locator devices support at least one form of echoing. Possible echoes are 
beeping, or displaying the point sampled. Refer to the Device Handlers 
Manual to determine the number and type of echoes supported by a specific 
locator device. If ECHO is larger than the number of echoes supported by 
the enabled locator device, then ECHO 1 will be used. 

Locator echoing can only be performed on the locator device. The locator 
echo position is not used in conjunction with any echoes performed while 
sampling a locator. 
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ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Logical locator device not currently enabled. 

ACTION: Call ignored. 

3) ECHO out of rainge. 

ACTION: Treated as if ECHO = 1. 
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PURPOSE: To sample the enabled valuator device and return the value of the 
subvaluator specified without waiting for operator response. 


CALLING SEQUENCE: CALL ZSVAL ( ECHO, SUBVAL, VALUE ) 


ECHO [ INTEGER; Input ] 

The level of input echoing. Legal values are: 

ECHO = 0 - No echo. 

1 to 255 “ Echo on the valuator device. 

SUBVAL [ INTEGER; Input ] 

The subvaluator which is to be sampled on the valuator 
device. (1 <= SUBVAL <= 255) 

VALUE [ REAL; Output ] 

The value returned from the subvaluator specified by 
SUBVAL on the enabled valuator device. (0.0 <= VALUE 
<= 1 . 0 ) 


ZSVAL returns the current value of the subvaluator in the variable VALUE 
without waiting for an operator response. VALUE will always range from 0.0 
to 1.0 inclusive. To wait for an operator response before returning the 
value of the valuator, see ZWVAL. 

A valuator device is considered to be a collection of one or more sub¬ 
valuator devices. SUBVAL is used to specify the subvaluator to be used when 
sampling the valuator. 

For example, the valuator device is simulated on the HP 9III Data Tablet by 
reading the position of the stylus on the platen. If SUBVAL is set to 1, 
the X position of the stylus is returned, with 0.0 represented as the ex¬ 
treme left side of the platen, and 1.0 represented as the extreme right 
side. If SUBVAL is set to 2, the Y position of the cursor is returned, with 
0.0 represented as the bottom of the platen, emd 1.0 represented as the top. 
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The number of subvaluators supported on a valuator device is device depen¬ 
dent but all valuators support at least one subvaluator. If SU6VAL is 
greater than the nvunber of supported subvaluators on the enabled valuator 
device, then the call will proceed as if SU6VAL were equal to 1. ZIWS with 
OPCODE equal to 70^1 can be used to determine the nvunber of valuators 
supported. 

The number of echoes supported by a valuator device and the correlation be¬ 
tween ECHO and the type of echoing performed is device dependent. Most 
valuator devices support at least one form of echoing. Possible echoes are 
beeping or displaying the value sampled. Refer to the Device Handlers 
Manual to determine the number and type of echoes supported by a specific 
valuator device. If ECHO is larger than the number of echoes supported by 
the enabled valuator device, then ECHO 1 will be used. Valuator echoing can 
only be performed on the valuator device. 

ZSVAL implicitly makes the picture current before sampling valuator. The 
logical valuator device should be enabled prior to calls to ZSVAL (see 
ZVINT). The valuator is disabled by calling ZVEND. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Logical valuator device not currently enabled. 

ACTION: Call ignored. 

3) ECHO out of range. 

ACTION: Treated as if ECHO = 1. 

4) SUBVAL not supported by the valuator device. 

ACTION: Treated as if SUBVAL = 1. 
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PURPOSE: To output graphics text on the graphics display. 


CALLING SEQUENCE: CALL ZTEXT ( NCHARS, STRING ) 


NCHARS [ INTEGER; Input ] 

The number of characters to be output. 
(1 <= NCHARS <= 132). 


STRING [ INTEGER; Array; Input ] 

Contains the characters to be output in Packed ASCII 
format. 


ZTEXT generates text on the graphics display. Text will be produced by a 
device’s hardware character generator, when present. Otherwise, text is 
simulated in software. 

A call to ZTEXT will output the characters contained in the array STRING to 
the graphics display. When the text string is output, the starting position 
is initially at the lower left-hand comer of the first character in STRING. 
Text is normally output from left to right and is printed vertically with no 
slant. Some devices support other text directions and character slants 
which can be accessed through escape f\inctions (see ZOESC). Refer to the 
Device Handlers Mantuil for additional text functions which may be supported 
by a specific graphics display device. 

After completion of this call, the starting position is left in a device¬ 
dependent location. Refer to the Device Handlers Ikmual for the effect of 
subsequent text primitives. A call to ZMOVE, ZPOLY, ZPGDI or ZPGDD should 
be made after this call to update the starting position. 

The actual character size used to generate text is device dependent since 
not all devices support continuously variable character sizes. If the ac¬ 
tual character cell size requested is not available on the graphics display, 
then the “smaller best fit" size available will be used. The smaller best 
fit character size is defined to be: 

o The largest character whose cell height is less than or equal to the 
requested height aind whose cell width is less than or equal to the 
requested width, or, 

o If the size requested is smaller than all available sizes, then the 
smallest available size will be used. 
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Since the DGL system does not perform software clipping, any portion of the 
string that lies either partially or entirely outside of the limits of the 
window will generate device-dependent results. 

The attributes of color, highlighting linestyle, linewidth and character 
size apply to text primitives. However, the text will appear with these at¬ 
tributes only if the graphics device is capable of applying them to text. 
Check the Device Handlers Manual for the exact capabilities of the display 
device used to determine the effect of all primitive attributes. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION; Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Logical graphics display not currently enabled. 

ACTION: Call ignored. 

3) NCHARS out of range (1 to 132). 

ACTION: Call ignored. 
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PURPOSE: To disable the enabled valuator device. 


CALLING SEQUENCE: CALL ZVEND { no parameters > 


ZVEND terminates and disables the enabled valuator device. It transmits auiy 
termination sequence required by the device and releases all resources being 
used by the device. The device name is set to the default device name (see 
the Device Handlers Manual) ^ the device status is set to 0 (not enabled) and 
the I/O unit descriptor of the device is set to 0. 

ZVEND is the complementary routine to ZVINT. 

If the valuator is used, ZVEND should be called before the application 
program is terminated. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Logical valuator device not currently enabled. 

ACTION: Call ignored. 
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PURPOSE: To set the boundaries of the viewport in the virtual coordinate 
system. 


CALLING SEQUENCE: CALL ZVIEW ( VXMIN, VXMAX, VYMIN, VYMAX ) 


VXMIN 


VXMAX 


VYMIN 


VYMAX 


[ REAL; Input ] 

The minimum boundary in the X direction expressed in 
virtual coordinates. 

[ REAL; Input ] 

The maucimum boundary in the X direction expressed in 
virtual coordinates. 


[ REAL; Input ] 

The minimum boundary in the Y direction expressed in 
virtual coordinates. 

[ REAL; Input ] 

The maximum boundary in the Y direction expressed in 
virtual coordinates. 


ZVIEW sets the limits of the viewport in the virtual coordinate system. The 
viewport must be within the limits of the virtual coordinate system; other¬ 
wise the call will be ignored. 

The initial viewport is: 


(VXMIN=0.0,VXMAX=1.0,VYMIN=0.0,VYMAX=1.0) 


The initial viewport is set by ZBEGN. This initial viewport is mapped onto 
the maximvim visible square within the logical display limits. This area is 
called the view surface. The placement of the view surface within the logi¬ 
cal display limits is dependent upon the device being used (see the Device 
Handlers Manual). It is generally centered on CRT displays and tubes and is 
usually placed in the lower left-hand comer of plotters. 
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By changing the limits of the viewport, an application program cam display 
an image in several different positions on the same graphics display device. 
A program can make a call to ZVIEW anytime the DGL system is initialized. 

The starting position is not altered by this call. Since this call 
redefines the viewing transformation, the starting position may no longer 
represent a known world coordinate position. A call to ZMOVE, ZPOLY, ZPGDD, 
or ZPGDI should be made after this call to update the starting position. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) XMIN >= XMAX or YMIN >= YMAX. 

ACTION: Call ignored. 

3) Either of the points (XMIN, YMIN) or (XMAX, YMAX) is not within the cur¬ 
rent virtual coordinate system boundary. 

ACTION: Call ignored. 
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PURPOSE: To define the boundaries of the window. 


CALLING SEQUENCE: CALL ZWIND ( WXMIN, WXMAX, WYMIN, WYMAX ) 


WXMIN [ REAL; Input ] 

The minimum bo\mdary in the X direction expressed in 
world coordinates, i.e., the left window border. 

WXMAX [ REAL; Input ] 

The maximum boundary in the X direction expressed in 
world coordinates, i.e., the right window border. 

WYMIN [ REAL; Input ] 

The minimxun boundary in the Y direction expressed in 
world coordinates, i.e., the bottom window border. 

WYMAX [ REAL; Input ] 

The maximum boundary in the Y direction expressed in 
world coordinates, i.e., the top window border. 


ZWIND defines the limits of the window. All positional information sent to 
and received from the DGL system is specified in world coordinate units. 
This allows the application program to specify coordinates in units related 
to the application. 

The window is linearly mapped onto the viewport specified by ZVIEW. This is 
done by mapping WXMIN to the minimum X viewport boundary, WXMAX to the maxi¬ 
mum X viewport boundary, WYMIN to the minimvun Y viewport boundary, and WYMAX 
to the maximum Y viewport bovmdary. If distortion of the graphics image is 
not desired, the aspect ratio of the window boundaries should be equal to 
the aspect ratio of the viewport. 

Since the DGL system does not perform software clipping, the results 
generated by specifying coordinates outside of the defined window are 
device dependent. 

The default window limits range from -1.0 to 1.0 on both the X and Y axis. 
ZBEGN sets the window to its default limits. 
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The starting position is not altered by this call. Since this call 
redefines the viewing transformation, the starting position may no longer 
represent a known world coordinate position. A call to ZMOVE, ZPOLY, ZPGDD, 
or ZPGDI should therefore be made after this call to update the starting 
postion. 

ZWIND can be called at auiy time vdiile the DGL system is initialized. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) XMIN = XMAX or YMIN = YMAX. 

ACTION: Call ignored. 
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PURPOSE: To wait imtil activation of the locator button and then read from 
the enabled locator device. 


CALLING SEQUENCE: CALL ZWLOC ( ECHO, LBUTN , Vffi, WY ) 

ECHO [ INTEGER; Input ] 

The level of input echoing. Possible values are: 

0 - No echo. 

1 - Echo on the locator device. 

2 - Track the position of the locator on the graphics 

display device. The initial position of the cursor 
is at the locator echo position. The point return¬ 
ed is the locator position. 

3 - Designate the position of the locator on the 

graphics display device with two intersecting 
lines. One line is horizontal with a length equal 
to the width of the graphics display surface. The 
other line is vertical with a length equal to the 
height of the graphics display device. The initial 
point of intersection is at the current locator 
echo position. The point returned is the locator 
position. 

U - Designate the endpoints of a line. One end is fixed 
at the locator echo position; the other endpoint is 
designated by the current locator position. This 
is usually referred to as a rubber band line. The 
point returned is the locator position. 

^ - Designate a horizontal line. One endpoint of the 
line is fixed at the locator echo position; the 
other endpoint has the world Y coordinate of the 
locator echo position euid the world X coordinate of 
the current locator position. The point returned 
will have the X coordinate of the locator position 
2und the Y coordinate of the locator echo position. 
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6 - Designate a vertical line. One endpoint of the 

line is fixed at the locator echo position; the 
other endpoint will have the world X coordinate of 
the locator echo position and the world 

Y coordinate of the current locator position. The 
point returned will have the X coordinate of the 
locator echo position and the Y coordinate of the 
locator position. 

7 - Designate a horizontal/vertical line. One endpoint 

of the line is fixed at the locator echo position. 
The other endpoint will have the world X coordinate 
of the locator echo position and the world 

Y coordinate of the current locator position or the 
world X coordinate of the current locator and the 
world Y coordinate of the locator echo position, 
depending on which point defines a longer line. 
If both lines are of equal length, a horizontal 
line will be used. As a result this echo defines 
either a horizontal or vertical line depending on 
whether the line from the locator echo position to 
the cunrent locator position is closer to the 
horizontal or the vertical. The point returned is 
the endpoint of the echoed line. 

8 - Designate a rectangle. The diagonal of the rec¬ 

tangle is the line from the locator echo position 
to the current locator position. The returned 
point will be the locator position. 

9 - 255 ■ Echo on the locator device. 


LBUTN [ INTEGER; Output ] 

The integer value of the button used to activate the 
locator input. (0 <= LBUTN <= 255)• 

WX,WY [ REAL; Output ] 

The world coordinate point returned from the enabled 
locator. The point may be outside of the current logi¬ 
cal locator limits. 


ZWLOC waits until the locator button is activated and then returns the value 
of the selected button and the world coordinate point (WX,WY) of the 
locator. Each locator device has its own set of buttons that may or may not 
be the same as those that comprise the button device. If an invalid button 
is pressed, LBUTN will be returned as 0; otherwise LBUTN will contain the 
value of the button pushed. 
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Several different t 3 ^es of echoing can be performed. Some echoes .are 
performed on the locator device while others use the graphics display 

device. When ECHO is in the range of 2 through 8, the graphics display 

device will be used. All of the echoes on the graphics display start at a 
point on the graphics display called the locator echo position (see ZLOCP). 
For some of these echoes the locator echo position is also used as a fixed 
reference point. For example, mainy devices support a rubber band echo. The 
fixed end of the rubber band line will be at the locator echo position. Not 
all graphics display devices can fully perform locator echoes 2 through 8. 
When an echo caumot be performed it will be simulated as closely as pos¬ 
sible. For exaunple the HP 2623 Graphics Terminal does not support a full 
screen cursor echo so it is simulated using the standard graphics cursor. 
The actual echo performed is dependent upon the locator and graphics display 
devices being used. Refer to the Device Handlers Manual for device specific 

information. If ECHO is in the range 2 through 8 and the graphics display 

device is disabled ECHO 1 will be used. 

ECHO values of 1 and 9 through 255 specify that the echo is to be performed 
on the locator device. Most locator devices support at least one form of 
echoing. Possible forms include beeping, displaying the value entered, or 
blinking a light each time a point is entered. If the specified echo is not 
supported on the enabled locator device, ECHO 1 will be used. 

ZWLOC implicitly makes the picture current before requesting locator input. 
The logical locator device should be enabled prior to calls to ZWLOC (see 
ZLINT). The locator is disabled by calling ZLEND. 

In some configurations of some devices the starting position may be left at 
a device-dependent location after this call. Refer to the Device Handlers 
Manual for details. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to Z6EGN must be made to initialize DGL. 

2) The locator device is not currently enabled. 

ACTION: Call ignored. 

3) ECHO is out of range. 

ACTION: Treated as if ECHO = 1. 

k) ECHO requires a graphics display device and the logical graphics display 
is not enabled. 

ACTION: Treated as if ECH0=1. 

5) Locator button activated is not valid. 

ACTION: LBUTN set to 0 and call proceeds. 
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ZWVAL 


PURPOSE: To wait until activation of the valuator button and then read from 
the specified subvaluator of the enabled valuator device. 

CALLING SEQUENCE: CALL ZWVAL ( ECHO, SUBVAL, VBUTN , VALUE ) 

ECHO [ INTEGER; Input ] 

The level of input echoing. Possible values are: 

ECHO = 0 - No echo. 

= 1 to 255 ■ Echo on the valuator device. 

SUBVAL [ INTEGER; Input ] 

The subvaluator which is to be read from the enabled 
valuator device. (1 <= SUBVAL <= 255) 

VBUTN [ INTEGER; Output ] 

The integer value of the button used to activate the 
valuator input. 

(0 <= VBUTN <= 255). 

VALUE [ REAL; Output ] 

The REAL value returned from the subvaluator specified 
by SUBVAL on the enabled valuator device. 

(0.0 <= VALUE <= 1.0) 

ZWVAL waits until the valuator button is activated and then returns the 
value of the selected button emd the value of the specified subvaluator. 
Each valuator device has its own set of buttons which may or may not be the 
same as those that comprise the button device. If an invalid button is 
pressed, VBUTN will be returned as 0; otherwise, the VBUTN will contain the 
value of the button pushed. VALUE will always range from 0.0 to 1.0. The 
desired echo and subvaluator are specified in the respective variables ECHO 
and SUBVAL. 

A valuator device is considered to be a collection of one or more sub¬ 
valuators. SUBVAL is used to specify which subvaluator on the enabled 
valuator will be used to perform the valuator function. 
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For exsunple, the valuator device is simulated on the HP 9111 Data Tablet by 
reading the position of the stylus on the platen. If the specified value of 
SUBVAL is 1, the X position of the stylus is returned, with 0.0 represented 
as the extreme left side of the platen, and 1.0 represented as the extreme 
right side. If SUBVAL is specified as 2, the Y position of the cursor is 
returned, with 0.0 represented as the bottom of the platen, and 1.0 
represented as the top. 

The nximber of subvaluators supported on a valuator device is device depen¬ 
dent but all valuators support at least one subvaluator. If SUBVAL is 
greater than the number of supported subvaluators on the enabled valuator 
device, then the call will proceed as if SUBVAL were equal to 1. ZIWS can 
be used to determine the number of subvaluators supported. 

The number of echoes supported by a valuator device and the correlation be¬ 
tween ECHO and the type of echoing performed is device dependent. Host 
valuator devices support at least one form of echoing. Possible echoes are 
beeping, or displaying the value sampled. Refer to the Device Handlers 
Manual to determine the number auid type of echoes supported by a specific 
valuator device. If ECHO is larger thsm the number of echoes supported by 
the enabled valuator device, then ECHO 1 will be used. 

ZWVAL implicitly makes the picture current before requesting valuator input. 
The logical valuator device should be enabled prior to calls to ZWVAL (see 
ZVINT). The valuator is disabled by calling ZVEND. 

In some configurations of some devices the starting position may be left at 
a device-dependent location after this call. Refer to the Device Handlers 
Manual for details. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The valuator device is not enabled. 

ACTION: Call ignored. 

3) ECHO out of rauige. 

ACTION: Treated as if ECHO = 1. 

k) Valuator button activated is not valid. 

ACTION: VBUTTN set to 0 and call proceeds. 
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Alphanumeric display device 

An output device to which non-graphics text and data may be directed. 
It is most often used to send prompts, give status and print other 
messages. 

Aspect ratio 

The ratio of the height to width of an area (e.g,, the area of a display 
device, the window, the viewport or the view surface). 

Attribute 

See Primitive attribute. 

Button input function 

An input function that returns an integer value corresponding to a but¬ 
ton or key that is activated. 

Character cell 

An imaginary box placed around a character which defines its dimensions. 
The character size attribute determines the size of the character cell. 

Clipping 

The elimination from view of all visible primitives or parts of primi¬ 
tives which lie outside the given limits. 

Color model 

A system within which displayable colors are defined. See also, HSL 
Model and RBG Model. Colors are defined by a triplet of real numbers in 
a range (0.0 to 1.0). 

Color table 

A table defining colors currently available for a graphical display 
device. Colors are defined by a triplet of real numbers in a range (0.0 
to 1.0) using the current color model. 

Default 

See Initial value. 
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Eavesdrop device 

A device connected between the host computer and a terminal which "lis¬ 
tens" to the data sent from the host computer. When a special escape 
sequence is sent, the device accepts all subsequent data and does not 
pass it on the terminal. When a second special escape sequence is sent, 
the device ignores all data and passes it on the terminal. 

Echoing 

A mechanism for reflecting the status of an input function. Echoing is 
manifested in several ways as a function of the different input func¬ 
tions and the different physical devices being used. 

Edge, member polygon 

See Polygon edge. 

Edge, polygon set 

See Polygon edge. 

Edge display 

The physical expression of a polygon edge, drawn on the graphics display 
device; an edge has the attributes of highlighting, color, linestyle 
and linewidth in effect at the time of polygon generation. 

Enable a device 

Enabling a device makes it available for use. A device must be enabled 
before requests are directed to it. 

Escape function 

A facility within DGL which allows access to device dependent functions 
of a graphics display device. 

Graphics display device 

A peripheral which displays graphics output. 

Highlighting 

A primitive attribute used to emphasize the primitive of an image. Some 
devices highlight by blinking or by increasing line intensity, others 
ignore the highlighting attribute. 

HSL model 

A perceptual color model which represents a color space as a cylinder 
whose angle about its axis is the hue, height is the luminosity, and 
radius is the saturation. See also. Color model. 
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Image 


A particular view of one or more objects or parts of objects. Images 
comprise the picture on a graphics display device. 

Immediate visibility 

A DGL timing mode in which picture changes requested by a DGL routine 
are sent to the graphics display device before the routine is exited. 
This is the least efficient timing mode in terms of system resource 
usage. 

Initiai value 

The value of an attribute, viewing component, or characteristic of a 
work station which is in effect when DGL is initialized. 

Inquiry 

User request for the current status, value, or characteristics of the 
graphics environment. 

Interior, polygon 

See Polygon interior. 

Interior Density 

See Polygon interior density. 

Interior Orientation 

See Polygon interior orientation. 

Keyboard input function 

An input function which returns a text string of zero or more charac¬ 
ters. The typical keyboard device is the alphanumeric keyboard. Keyboard 
input is terminated when a termination character (e.g. carriage return) 
is detected. 


Line 


A vector drawn from the current position to a specified point. 

Linestyle 

An output primitive attribute which controls the pattern with which 
lines, polylines, polygon edges and text primitives are drawn. 

Linewidth 

An output primitive attribute which controls the thickness with which 
lines, polylines, polygon edges and text primitives are drawn. 
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Locator input function 

An input function which returns a virtual coordinate point corresponding 
to a location on a locator device♦ 

Logical device 

An abstraction of a typical graphics device, defined in terms of the 
type of data input or output. The logical devices supported by DGL are 
button, keyboard, locator, valuator, alphanumeric display and graphics 
display. 

Logical display limits 

The bounds of the logical display surface. 

Logical display surface 

The portion of a graphics display device where all output will appear. 

Make-picture-current 

Action which forces all currently buffered updates to be sent immediate¬ 
ly to the display device. 

Mapping 

The transformation of data from one coordinate system to another. 

Marker 

An output primitive that is a center oriented symbol used to identify a 
point in the world coordinate system. 

Member polygon 

A polygon which is an element of a polygon set. See Polygon. 

Move 

Moving the starting position to a specified point without generating a 
line. 

New-frame-action 

The elimination from view of all primitives. On most devices this means 
the screen will be erased. On chart advance plotters the paper is 
advanced. 

Object 

The conceptual graphics entity in the application program. Objects are 
defined in terms of output primitives and primitive attributes. Their 
units are the units of the world coordinate system. 
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Output primitive 


The basic element of an object. The output primitives which DGL supports 
are: move, line, polyline, polygon, marker and text. Values of the 
primitive attributes determine aspects of the appearance of output 
primitives. 

Packed ASCII Format 

The format in which input characters are returned or given: ASCII left- 
justified, one character per byte and blank filled. 

Picture 

A collective reference to all the images on a display device. 

Pixel 

The smallest element of a display surface that can be independently as¬ 
signed a color or intensity; a picture element. 

Polygon 

An output primitive that defines a multi-sided closed figure, including 
the surface defined by its boundary. 

Polygon boundary 

The outer limit of a polygon surface. The interior of the polygon is 
defined to include the boundary. 

Polygon edge 

A characteristic of the polygon style attribute. For each entry in the 
polygon style table, a polygon edge is specified as present or absent. 
If an edge is present, it is superimposed on the boundary of the polygon 
and is genera^ted with the current attributes of linestyle, highlighting, 
linewidth and color. 

Polygon interior 

The area defined by the boundary of a polygon, including the boundary 
itself. 

Polygon interior color 

A polygon attribute that defines the color of the interior of sub¬ 
sequently generated polygons. This attribute is an index into a device¬ 
dependent color table. 
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Polygon interior density 

A characteristic of the polygon style attribute. For each entry in the 
polygon style table the interior density is specified as the ratio of 
filled area to total area in a polygon's interior (based on a solid 
linestyle). 

Polygon interior orientation 

One characteristic of the polygon style attribute. For each polygon 
style entry in the polygon style table, an interior orientation is 
specified. It defines whether the pattern which fills the interior of 
the polygon is to be hatching or cross-hatching. It also defines the 
angle of orientation of the fill lines to the view surface. 

Polygon style 

A polygon attribute that defines the density of the polygon interior, 
the orientation of the polygon interior, the presence or absence of a 
polygon edge. This attribute is an index into a work station dependent 
polygon style table. 

Polygon style table 

A device dependent table of polygon styles. Each table entry defines 
the polygon interior density, the polygon interior orientation, and the 
polygon edge flag. 

Polyline 

An output primitive which defines a connected sequence of lines. 

Primitive 

See Output primitive. 

Primitive attribute 

A characteristic of an output primitive, such as color, linestyle, or 
text font. 

Requested input 

An input operation which requests data and completes when an operator 
enters a termination command. 

RGB Model 

A color model which represents a color spatially as a cube that has as 
its three axes the primary additive colors; red, green and blue. See 
also. Color model. 
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Sampled input 


An input operation which does not require operator intervention; the 
routine returns with the current value as soon as the input device can 
respond. 

System buffering 

A DGL timing mode in which picture changes requested by a DGL routine 
are subject to buffering. 

Timing mode 

Used to control DGL execution efficiency and the immediacy of visual 
changes to a graphics display device. DGL has two timing modes: im¬ 
mediate visibility and system buffering. 

Valuator input function 

An input function which returns a numeric value within the range (0.0 to 
1.0) inclusive. The typical valuator is the control dial (poten¬ 
tiometer) , but multi-position switches and toggle switches can be util¬ 
ized as low-precision valuators. 

Viewing operation 

See Viewing transformation. 

Viewing transformation 

An operation which maps positions in the world coordinate system to 
positions in device coordinates, thereby transforming objects into 
images. 

Viewport 

The rectangular region of the view surface onto which the window will be 
mapped. 

View surface 

The largest rectangle within the logical display limits having the same 
aspect ratio as the virtual coordinate system. 

Virtual coordinate system 

A two-dimensional coordinate system representing an idealized display 
device. Virtual coordinates are always in the range 0.0 < (X,Y) ^ 1.0. 
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Window 


A rectangular region in world coordinates which is linearly mapped onto 
the viewport. 

Work station 

A collection of graphics devices that can be treated as a \mit. 

World coordinate system 

The two-dimensional left-handed Cartesian coordinate system in which ob¬ 
jects are described by the user program. 
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A 


Alphamumeric Device 

Disabling (ZAEND), 3-2 
Usage (ZALPH), 3-3 
Alphanumeric Output 
Concepts, 1-10 
ZALPH, 2-12- 
Aspect Ratio 

Concepts, 1-8, 2-25 
ZASPK, 2-27, 3-5 


B 


Button Device 

Disabling (ZBEND), 3-8 
Usage (ZBUTN), 3-11 
ZBUTN, 2-33 


c 


Character 

Cell, 2-20, 3-17 
Size (ZCSIZ), 2-20, 3-17 
Character size inquiry, 2-1*3 
Color attribute 
inquiry, 2-1+3 
Related calls, 2-ll+ 

ZCOLM, 2-llt, 3-13 
ZCOLR, 2-11+, 3-15 
ZDCOL, 2-11+, 3-19 
ZPICL, 2-14, 3-64 
Color modelling 
Concept, 2-14 
Related calls, 2-l4 
ZCOLM, 2-l4, 3-13 
ZDCOL, 2-14, 3-19 

Color, polygon interior. See Polygons -- interior color, 2-14 
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Concepts 

Alphanumeric Output, 1-10 

Aspect Ratio, 1-8, 2-25 

Color modelling, 2-lk, 3-1> 3-19 

Control, 1-9» 2-38 

Device Control, 2-39 

Draw, 1-3 

Graphics Output Primitives, l-3> 2-U 
Input, 1-9 

Input Primitives, 2-32 

Logical Button Device, I-9 

Logical Display Limits, 1-7? 2-25 

Logical Display Surface, 2-25 

Logical Input Devices, I-9 

Logical Keyboard Device, I-9 

Logical Locator Device, I-9 

Logical Valuator Device, 1-9? 2-37 

Marker, I-3 

Move, 1-3 

Output, 2-U 

Polygon, 1-3 

Polyline, 1-3 

Primitive Attributes, I-5 

Requesting Input, I-9 

Sampling Input, I-9 

Starting Position, 1-U 

Text, 1-3 

View Surface, 2-25 
Viewing Transformations, 1-6, 2-23 
Viewport, 1-7? 2-25 
Virtual Coordinate System, 2-25 
Window, 1-7, 2-25 
World Coordinate System, 1-U 
Continuous Linestyle, 2-l8, 3 -U 9 
Control 

Concepts, 1-9, 2-38 
Device, 2-39, 3-22 
Escape Functions, 2-UU 
Escape Functions (ZIESC), 3-3U 
Escape Functions (ZOESC), 3-56 
Inquiry Functions, 2-U3 
Inquiry Fvinctions (ZIACS), 3-32 
Inquiry Fvinctions (ZIWS), 3-36 
Making picture current, 2-U2, 3-53 
New-frame-action (ZNEWF), 2-Ul 
System (ZEND), 3-30 
System Control (ZBEGN), 2-38, 3-7 
System Control (ZEND), 2-38 
Timing Modes (ZBMOD), 2-U2, 3-9 
Conversion of Units 

Display (ZDPMM), 2-31, 3-25 
Locator (ZLPMM), 2-35, 3-U7 
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D 


Device Control Concepts, 2-39 
DGL 

Functions,General, 2-1 

System Initialization (ZBEGN), 3"7 

System Structure, 1-1 


E 


Echoing, 2-32 
Locator, 2-36 
Enable 

Graphics Display Device, 2-UO 
Other devices, 2-4l 
Error Reporting, 3”1 
Escape Functions 
ZIESC, 3-34 
ZOESC, 3-56 


G 


Graphics Display Device 
Control, 2-40 
Disabling (ZDEND), 3-22 
Locator Echo Position (ZLOCP), 3-45 
Graphics output primitives. Attributes that affect them, 2-13 


H 


Highlighting Attribute 
ZHIGH, 2 - 17 , 3-31 
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I 


Immediate Visibility Mode, 2-k2 
Input Primitives 
Concepts, 2-32 
Echoing, 2-32 
Inquiry Functions 
ZIPST, 3-36 

ziws, 3-32 


K 


Keyboard Device 

Disabling (ZKEND), 3-38 
Usage (ZKYBD), 3-39 
ZKYBD, 2-3h 


L 


Lines 

ZDRAW, 2-5, 3-29 
ZPOLY, 2 - 5 , 3-68 
Linestyle Attribute 

Continuous, 2-18, 3-^9 
Start-Adjusted, 2-l8, 3-^8 
Vector-Adjusted, 2-l8 
Vector-Adjusted, 3-^9 
ZLSTL, 2 - 17 , 3-1+8 
ZPILS, 2 - 17 , 3-66 

Linewidth 

Attribute (ZLWID), 3-50 
ZLWID, 2-19 
Locator Device 

Disabling (ZLEND), 3-1+1 

Limits, 2-35 

Limits (ZLLIM), 3-1+2 

Locator Echo Position (ZLOCP), 3-1+5 

Requesting, 2-36 

Sampling, 2 - 36 , 3-71 

Usage (ZWLOC), 3-82 

ZLLIM, 2-35 

ZLPMM, 2-35 

Locator Echo Position (ZLOCP), 3“l+5 
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Logical Alphanumeric Device 
Disabling (ZAEND), 3-2 
Usage(ZALPH), 3-3 

Logical Button Device 
Concepts, I -9 
Disabling (ZBEND), 3-8 
Usage (ZBUTN), 3-11 
ZBUTN, 2-33 

Logical Devices, 1-1, 2-3» 2-32 
Control, 2-39, 2-4l 

Logical Display Limits 
Concepts, 1-7, 2-25 
ZDLIM, 2-26 

Logical Display Surface 
Concepts, 1-9, 2-25 

Logical Keyboard Device 
Concepts, I -9 
Disabling (ZKEND), 3-38 
Usage (ZKYBD), 3-39 
ZKYBD, 2-34 

Logical Locator Device 
Concepts, 1-9, 2-34 
Disabling (ZLEND), 3-4l 
Limits, 2-35 
Limits (ZLLIM), 3-42 
Locator Echo Position (ZLOCP), 3-45 
Requesting, 2-36 
Sampling, 2 - 36 , 3-71 
Usage (ZWLOC), 3-82 
ZLLIM, 2-35 
ZLPMM, 2-35 

Logical Valuator Device 
Concepts, 1-9, 2-37 
Disabling (ZVEND), 3-77 
Requesting, 2-38 
Sampling, 2-38, 3-73 
Usage (ZWVAL), 3-85 


M 


Markers 

ZMARK, 2-8, 3-51 
Moves 

ZMOVE, 3-54 
ZPOLY, 3-68 



N 


New-frsime-action, 2-1+1, 3-55 


P 


Polygon Attribute 
ZPICL, 3-64 
ZPILS, 3-66 
Polygon style 
ZDPST, 2-21 
ZPSTL, 2-21 
Polygons 

Attributes,See Polygon style, 2-21 
Interior color,Related calls, 2-l4 
Interior color,ZPICL, 2-l4 
Style inquiry, 2-43 
ZPGDD, 2-9 
ZPGDI, 2-9 

Polyline ZPOLY, 3-68 
Primitive attributes 

Color, See Color attribute, 2-l4 
Concept, 1-5 
Description, 2-13 

Output primitives affected by, 2-13 


R 


Requesting Input 
Concepts, I -9 
Description, 2-32 
Locator, 3-82 
Valuator, 2-38, 3-85 
ZWLOC, 2-36 


s 


Sampling Input 
Concepts, 1~9 
Description, 2-32 
Valuator, 2-38 
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ZSLOC, 2 - 36 , 3-71 
ZSVAL, 3-73 

Smaller Best Fit Algorithm, 2-21 
Start-Adjusted Linestyle, 2-l8, 3-^8 
Starting Position 
Concepts, 1-4 
ZMOVE, 2-4, 3-54 
System Buffering Mode, 2-42 
System-Specific Calls, 3-1 


T 


Tables 

Aspect Ratio Limits, 2-27 
Graphics Primitives, 2-13 
Standard Markers, 2-8 
Text 

Character Size, 2-20, 3-1, 3-32 
ZTEXT, 2-6, 3-75 
Timing Modes, 2-42 
XMCUR, 3-53 
ZBMOD, 3-9 


V 


Valuator Device 
Concepts, 2-37 
Disabling (ZVEND), 3-77 
Requesting, 2-38 
Sampling, 2-38, 3-73 
Usage (ZWVAIr), 3-85 
Vector-Adjusted Linestyle, 2-l8, 3-49 
View Surface 

Concepts, 2-25 
Placement, 2-28 
Viewing Transformation 

Aspect Ratio (ZASPK), 3-5 
Concepts, 1-6, 2-23 
Logical Display Limits (ZDLIM), 3-23 
ZVIEW, 3-78 
ZWIND, 3-80 
Viewport 

Concepts, 1-7, 2-25 
ZVIEW, 2 - 28 , 3-78 
Virtual Coordinate System 
Aspect Ratio, 2-26 
Concepts, 2-25 

Logical Display Limits, 2-26 



w 


Window 

Concepts, 1-7, 2-25 
ZWIND, 2-31, 3-80 
Work Station Concepts, 2-3 
World Coordinate System Concepts, 1-4 


z 


ZAEND 

Definition, 3-2 
Description, 2-4l 
ZAINT Description, 2-4l 
ZALPH 

Definition, 3-3 
Description, 2-12 
ZASPK 

Definition, 3-5 
Description, 2-27 
ZBEGN 

Definition, 3-7 
Description, 2-38 
ZBEND 

Definition, 3~8 
Description, 2-4l 
ZBINT Description, 2-41 
ZBMOD 

Definition, 3-9 
Description, 2-42 
ZBUTN 

Definition, 3-11 
Description, 2-33 
ZCOLM 

Definition, 3-13 
Description, 2-l4 
Related calls, 2-l4 
ZCOLR 

Definition, 3-15 
Description, 2-l4 
Related calls, 2-l4 
ZCSIZ 

Definition, 3~17 
Description, 2-20 
ZDCOL 

Definition, 3-19 
Description, 2-l4 
Related calls, 2-l4 
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ZDEND 

Definition, 3"22 
Description, 2-UO 
ZDINT Description, 2-40 
ZDLIM 

Definition, 3-23 
Description, 2-26 
ZDPMM 

Definition, 3-25 
Description, 2-31 
ZDPST 

Definition, 3-26 
Description, 2-21 
Related calls, 2-21 
ZDRAW 

Definition, 3-29 
Description, 2-5 
ZEND 

Definition, 3-30 
Description, 2-38 
ZHIGH 

Definition, 3-31 
Description, 2-17 
ZIACS 

Definition, 3-32 
Description, 2-U3 
ZICOL 

Definition, 3-33 
Description, 2-U3 
ZIESC 

Definition, 3-3^ 
Description, 2-44 
ZIPST 

Definition, 3-36 
Description, 2-43 
ZIWS Description, 2-43 
ZKEND 

Definition, 3-38 
Description, 2-4l 
ZKINT Description, 2-4l 
ZKYBD 

Definition, 3-39 
Description, 2-34 
ZLEND 

Definition, 3-41 
Description, 2-4l 
ZLINT Description, 2-41 
ZLLIM 

Definition, 3-42 
Description, 2-35 
ZLOCP 

Definition, 3-45 
Description, 2-36 



ZLPMM 

Definition, 3-^7 
Description, 2-35 
ZLSTL 

Definition, 3-^8 
Description, 2-17 
ZLWID 

Definition, 3“50 
Description, 2-19 
ZMARK 

Definition, 3-51 
Description, 2-8 
ZMCUR 

Definition, 3-53 
Description, 2-42 
ZMOVE 

Definition, 3-54 
Description, 2-4 
ZNEWF 

Definition, 3“55 
Description, 2-4l 
ZOESC 

Definition, 3"56 
Description, 2-44 
ZPGDD 

Definition, 3"58 
Description, 2-9 
ZPGDI 

Definition, 3-61 
Description, 2-9 
ZPICL 

Definition, 3-64 
Related color calls, 2-l4 
ZPILS 

Definition, 3-66 
Description, 2-17 
ZPOLY 

Definition, 3-68 
Description, 2-5 
ZPSTL 

Description, 2-21 
Related calls, 2-21 
ZSLOC 

Definition, 3“71 
Description, 2-36 
ZSVAL 

Definition, 3-73 
Description, 2-38 
ZTEXT 

Definition, 3-75 
Description, 2-6 
ZVEND 

Definition, 3-77 
Description, 2-4l 
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ZVIEW 

Definition, 3“78 
Description, 2-28 
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ZIPGI 


The attributes of color, polygon interior color, highlighting linestyle, 
polygon interior linestyle eind linewidth apply to polygon primitives. 
However, the polygons will appear with these attributes only if the graphics 
device is capable of applying them to polygons. Check the DeV%ce Handlers 
Manual for the exact capabilities of the display device used to determine 
the effect of all primitive attributes. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) NPOINT is a non-positive integer. 

ACTION: Call ignored. 

U) The nismber of vertices specified in IXVEC, lYVEC exceeds 500• 

ACTION: The polygon set is outlined. 

5) OPCODE(1) does not equal 2. 

ACTION: Call ignored. 

6) OPCODE(i) (i >1) does not equal 0, 1, or 2. 

ACTION: The polygon set is drawn but the results are unpredictable. 

7) An interior fill line crosses the edge of the polygon set too many 
times. See Section I ("Polygon Intercept Buffer Size Chainges"). 

ACTION: The fill line is not drawn. 
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PREFACE 


Who needs to use this manual? 


The DGL Suppleimnt for HP-UX Systems complements the DGL Programmer 
Reference Manual and is intended for users of Hewlett-Packard's 
Device-independent Graphics Library (DGL). The Supplement presents DGL 
reference information which is specific to the HP-UX operating system. 


How is it organized? 

The DGL Supplement for HP-UX Systems is divided into three parts. Part I 
contains HP-UX Operating System topics such as programming requirements, 
user-modifiable graphics tables, and other HP-UX system-specific topics. 
Part II describes calls which are operating system dependent. Part III 
describes graphics integer interface calls. 

Calls in Parts II and III have the same format as those in the ZX?L 
Programmer Reference Manual . You may insert these calls in the Reference 
Manual (in alphabetical order) or use the Supplement as is. 
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DGL SUBROUTINES AND PARAMETERS 


ZAEND (no parameters) 

ZAINT (lODLEN.IODESJJE^) 

ZALPH (NCHARS,STRING) 

ZASPK (XSIZE.YSIZE) 

ZBEGN (no parameters) 

ZBEND (no parameters) 

ZBINT (lODLENJODES.IERR) 

ZBMOD (OPCODE) 

ZBUTN (ECHO,BUTTON) 

ZCOLM (MODEL) 

ZCOLR (COLOR) 

ZCSIZ (WIDTH, HEIGHT) 

ZDCOL (COLOR,COLP1,COLP2.COLP3) 

ZDEND (no parameters) 

ZDINT (IODLEN,IODES,CONTRL,!ERR) 

ZDLIM (XMlN.XMAX.YMIN.YMAX.Igf^) 

ZDPMM (WX,WY,MJ^,^MY) 

Z DPST (PINDEX.DENSTY,ORIENT,EDGE) 
ZDRAW (WX,WY) 

ZEND (no parameters) 

ZHIGH (HLIGHT) 

ZIACS (DWIDE.DHIGH,AWIDE.AHIGH) 

ZICOL (COLOR,CpLM,CC^^,CplP3) 

ZIDRW (lX.IY) 

Z lESC (OPCODE,ISIZE,RSIZE,IUST,RLIST,IERR) 
ZIMOV (lX.IY) 

ZIPGD (NPTS.IXVEC.IYVEC,OPCODE) 

ZIPGI (NPTS,IXVEC,IYVEC,OPCODE) 

ZIPLY (NPTS,IXVEC,IYVEC) 

ZIPST (PINDEX,DENSTY.ORIENT.EDGE) 

ZIWS (OPCODE,SSIZE,ISIZE.RSIZE,SLIST,ILIST, 
RLIST,IERR) 


ZKEND (no parameters) 

ZKINT (IODLEN,IODES,!ERR) 

ZKYBD (ECHO.MAX.ACTUAL.STRING) 

ZLEND (no parameters) 

ZLINT (IODLEN,IODES,!ERR) 

ZLLIM (XMIN,XMAX,YMIN,YMAX.[ERR) 

ZLOCP (WX,WY) 

ZLPMM (WX,WY,MMX,^MY) 

ZLSTL (LSTYLE) 

ZLWID (LWIDTH) 

ZMARK (MARKNO) 

ZMCUR (no parameters) 

ZMOVE (WX,WY) 

ZNEWF (no parameters) 

Z OESC (OPCODE,ISIZE,RSIZE,ILIST.RLIST.tERR) 
ZPGDD (NPOINT,XVEC,YVEC,OPCODE) 

ZPGDI (NPOINT.XVEC.YVEC.OPCODE) 

ZPICL (COLOR) 

ZPILS (LSTYLE) 

ZPOLY (NPTS,XVEC,YVEC) 

ZPSTL (PINDEX) 

ZSLOC (ECHO.WX.WY) 

ZSVAL (ECHO,SUBVAL,^J^yE) 

ZTEXT (NCHARS,STRING) 

ZVEND (no parameters) 

ZVIEW (VXMIN,VXMAX,VYMIN,VYMAX) 

ZVINT (IODLEN,IODES.!ERR) 

ZWIND (WXMIN,WXMAX,WYMIN,WYMAX) 
ZWLOC (ECHO,LBUTN. WX , WY ) 

ZWVAL (ECHO,SUBVAL,^iUTN,^J^yE) 


VI 



Part 1 

System-Dependent Topics 


Operating Environment 

DGL is supported on the HP-UX operating system. 

I/O Unit Descriptors 

The I/O unit descriptor specified in the initializatin calls is a device file. To create this file, 
use the mknod command described in the HP-UX System Administrator manual and the HP-UX 
Reference. 

Programming Languages 

Fortran 

Usless otherv^ise specified, the FORTRAN compiler defaults all integers to 342 bits, but DGL 
requires 16 bit integers. To assign 16 bit integers, use one of the following methods: 

• Use the compiler option, $0PTI0N SHORT INTEGERS. 

♦ Use the -12 option in the run string for the compiler. 

Characters must be passed to DGL in integer arrays. Do this with data statements, as shown 
in the program example on the following page. 
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A file^ /usr/lib/graphics/fortran/fdgll.h, is supplied with DGL containing 
aliases to the DGL routine names which are more English-like. The contents 
of this file may be copied to a local directory and modified as needed. To 
use these names, include this file in a DGL program as follows: 

$INCLUDE ’/usr/lib/graphics/fortraLn/fdgll.h’ 

The following FORTRAN example is complete. It may be typed into the com¬ 
puter and executed, or it may be modified to include many of the program 
fragments which are listed in the DGL Progmnwer Reference Manual, 


$OPTION SHORT INTEGERS 
PROGRAM USER 
C 

C..DGL user program to draw a line. 

C The graphics output is hard coded to /dev/crtgraphics 
C 

C..Set up variables 
C 

INTEGER^'P I0DES(8), lODLEN, lERR, CNTRL 

DATA I0DES/2H/d,2Hev,2H/c,2Hrt,2Hgr,2Hap,2Hhi,2Hcs/ 

DATA IODLEN/16/ 

C 

C..Initialize the system 
C 

CALL ZBEGN 
C 

C..Initialize the graphics display device 
C at /dev/crtgraphics with no control bits set. 

C 


CNTRL = 0 


C 

CALL ZDINT(IODLEN, lODES, CNTRL, lERR) 

C 

C 

C..Everything between the comment lines may be changed as needed. 
CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 
C 

C..Use default attributes and viewing transformation to draw line 
C diagonally across the display. 

C 

CALL ZMOVE (-1.0,-1.0) 

CALL ZDRAW (1.0,1.0) 

C 

CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC 

c 

C..Disable the graphics display device, end the DGL system, 

C and terminate this prograan. 

C 

CALL ZDEND 
CALL ZEND 
END 
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Pascal 


In general, the difficulties which arise when accessing DGL routines are 
those which arise when accessing any non-Pascal routine from a Pascal 
prograjn. Therefore, a review of that topic in the Pascal Manual may be 
useful. 

Parameters (paraml, param2, ...) passed to DGL routines must be declared 
VAR, or "call-by-reference". Note that any external routine may modify the 
actual parameters passed to it. However, DGL does not modify input para¬ 
meters. All DGL routines should be declared as external procedures as 
follows: 


PROCEDURE DGL_routine 

(VAR paraml : typel; 
VAR param2 : type2; 


VAR paramN : typeN); 
EXTERNAL; 


The following files are supplied with DGL: 


/usr/lib/graphics/pascal/pdgll.h 
/usr/lib/graphics/pascal/pdgl2.h 


These files provide standard data types and external declarations for inclu¬ 
sion in all application programs. The file pdgl2.h contains declarations 
for the standard DGL rountine names as well as aliases to a set of more 
English-like names. The contents of these files may be copied to a local 
directory and modified as needed. 

The application prograim must use the data types which DGL expects. 
Unfortunately, Pascal’s and FORTRAN’S data types are not always equivalent. 
The Pascal user should therefore declare and use appropriate data types for 
both the formal and actual parameters of DGL routines. One example of this 
incompatibility is the data type INTEGER. Pascal represents integers in 32 
bits, while DGL’s FORTRAN code always assumes them to be l6 bits. 
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The following declarations cause the variable "graphics^id" to be stored in 
a l6 bit integer: 

TYPE 

INT = -32768..32767; 

VAR 

graphics^id : INT; 


The following table summarizes correspondences between DGL parameters and 
matching Pascal data types. A file containing standard data-type declara¬ 
tions for Pascal is supplied with the DGL product. 


DGL expects 
Integer 

Character string 
of n characters 

Real 

Array of n integers 
A PASCAL version of program USER 


Pascal data type 

-32768..32767 

PACKED ARRAY[l..n] OF CHAR or 
ARRAY [1..n] of CHAR 

REAL 

ARRAY [l..n] OF -32768..32767 
is shovm below. 
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$PASCAL 

PROGRAM user; { DGL user program to draw a line } 

{ The following include files are part of the DGL product ) 
$INCLUDE ’/usr/lib/graphics/pas cal/pdgll.h * $ 

var 

ierr : INT; 

control : CONTROL_WORD; 
iodes : STRING132; 
iodlen : INT; 

xmin, xmax, ymin, ymax : REAL; 

$INCLUDE ’/usr/lib/graphics/pascal/pdgl2.h’$ 

BEGIN { Main of user } 

{ Initialize variables } 
iodlen := l6; 

iodes := ’/dev/crtgraphics’; 

xmin := -1.0; 

xmax := 1.0; 

ymin := -1.0; 

ymax := 1.0; 

control := control_spooling_off; 


{ Initialize the DGL system. } 

zbegn; 

{ Initialize a graphics display device at /dev/crtgraphics with ) 
{ no control bits set} ) 

zdint ( iodlen, iodes, control, ierr ); 

{ Everything between the dashes may be changed as needed ) 

( --- } 

{ Using default attributes and viewing transformation, draw line) 
{ diagonally across the display ) 

zmove ( xmin, ymin ); 
zdraw ( xmax, ymax ) ; 

{ --- > 

{ Disable the graphics display device and end the system } 

zdend; 
zend; 

END. { Main of User} 
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c 


In general, the difficulties which arise when accessing DGL routines are 
those which arise when accessing any FORTRAN routine from C. See the 
FORTRAN manual for a discussion of the FORTRAN/C interface. 

The user must pass actual parameters (paraml, param2, ...) to DGL routines 
by reference only. Therefore, all actual parameters passed to DGL must be 
pointers or variables prefixed with the address operator (&). All formal 
parameters returned from DGL must be pointer variables. All integers para¬ 
meters should be declared as short integers and all reals as float. 

DGL expects character parameters to be passed in integer arrays. C prograon- 
mers can pass these in one of two ways: 

1. use an array of short integers and a character pointer to the array; 
assign the characters individually using the character array (see C 
program below). 

2. pass a double-quoted character string. For example, the zdint call in 
the C program could have been coded: 

zdint (&iodlen,"/d^v/crtgraphics",&control,&ierr); 

In either case, the number of characters in the string passed must be at 
least the length specified. For character output, DGL requires a pointer to 
an array of short integers. 

The following table summarizes correspondences between DGL parameters and 
matching C data types. User-supplied names are bracketed by <>. Characters 
are packed two per element in a short integer array and require (n+l)/2 ele¬ 
ments to store n characters. For example, 15 characters could be stored in 
an array declared short string[8]. 


DGL expects 
Integer 

Character string 
of n characters 
(see note above) 

Real 


C data type 
short 

short < arrayname > [(n+1)/2] 


float 


Array of n integers short <arrayname> [n] 

A file, /usr/lib/graphics/c/cdgll.h, is supplied with the DGL product. It 
contains macro defintions of more English-like names. The contents of this 
file may be copied to a local directory and modified as needed. To use 
these names, include this file in a DGL program as follows: 


#include "/usr/lib/graphics/c/cdgll.h" 
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A C version of program USER is shown below 


main () 

{ I* begin main of user*/ 

/* DGL user program to draw a line. * 

/* The graphics output is hard-coded to /dev/crtgraphics. * 


short iodlen,iodes[8],control»ierr; 

float xmin,xmax,ymin,ymax; 
char *ioces = (char *)iodes; 


/* Initialize the DGL system * 


zbegn(); 

/* Initialize the graphics display device at * 

/* /dev/crtgraphics with no control bits set. * 


iodlen = l6; 
ioces[0] = ’/’; 
ioces[l] = ’d’; 
ioces[2] = ’e*; 
ioces[3] = *v’; 
ioces[Ui = ’/’» 
ioces[5] = ’c’; 
ioc6s[6] = ’r*; 

iocesili = ’t’; 

ioces[8] = ’g’; 
ioces[9] = ’r’; 
ioces[10] = ’a’; 
ioces[ll] = ’p*; 
ioces[l2j = ’h’; 
iocesilS] = ’i’; 
iocesilU] = ’c*; 
ioces[15] = ’s’; 
control = 0; 

zdint(&iodlen, iodes ,?ccontrol,&irerr); 


/* Everything between the dashes may be changed as needed * 

j* _ * 

l*¥k*******¥i>****¥i**Vk*¥!**¥i*¥i>lk¥i*¥i*Vmi**‘*mm*^**¥i%***¥k***¥t***m¥i¥i^**** 

I* Use default attributes and viewing transformation * 

/* to draw a line diagonally across the display. * 


/ 

/ 

/ 

/ 


/ 

/ 

/ 


/ 

/ 

/ 

/ 


/ 

/ 

/ 

/ 

/ 

/ 

/ 
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xmin = -1.0; 

xmax = 1.0; 

ymin = -1.0; 

ymaix = 1.0; 

zmove (&xmin,&ymin); 

zdraw (&xmax,&ymax); 


I* ----V 

Disable graphics display device and end the DGL system */ 

zdend(); 
zend(); 

} end main of user 


LIBRARY NAMES 


This supplement refers to libraries in the S2une way they are referenced 
using the -1 option on the linker. By adding the appropriate prefix and 
suffix to these names, the files can be found in the /lib directory. For 
example, the file name for the DOO3I library is /lib/libD0031*a and for 
DIDD, /lib/libDIDD.a. 


LINKING DGL PROGRAMS 


When linking DGL application programs, the user must be sure to search a 
device handler for each logical device accessed by the program. If the 
program uses the graphics display, it must be the last device hauidler sear¬ 
ched. Search the DGL library (DIDD) after searching all the device 
handlers. 

Because DGL is written in FORTRAN and C, the user must search the FORTRAN, C 
and math libraries for every link procedure. Shown below is the compile and 
link procedure for ain application program which accesses the following: 

the graphics display device on the HP 7^70A Plotter, 
the locator on the HP 7580B Drafting Plotter and 
the button device on the HP 9IIIA Data Tablet. 

Note that in these examples some libraries are automatically searched, and 
therefore, do not have to be specified in the run string. 
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For FORTRAN: 


fc program.f -1B004 -1L006 -1D0031 -IDIDD 
For Pascal: 

pc program.p -1B004 -1L006 -1D0031 -IDIDD -1F77 -1177 
For C: 

cc program.c -1B004 -1L006 -1D0031 -IDIDD -1F77 -1177 -Im 

See the HP-UX documentation for details of additional compiler and linker options. 

If the application program references a logical device but does not explicitly load a device handler 
for the device, a dummy device handler is automatically loaded. For example, if the application 
program calls ZBINT but the load procedure does not search for a button device hander (Bxxxx), 
a dummy device handler is implicitly loaded from DIDD. 


Special Information for Starbase Handlers 

There are five handlers which communicate with another software product rather than commu¬ 
nicating directly with a device. These handlers are: 

• B0056 

• L0056 

• P0056 

• V0056 

• D0056 

These function in the same way as other handlers except for two areas: program linking (using the 
pc or Id system commands) and device initialization (using the zdint or zbint DGL commands). 

When calling the device initialization routines for the DGL to Starbase handler, there is a small 
change in the second parameter. Currently, ZBINT, ZDINT, ZLINT, ZVINT, and the AGP 
calls JDINT and JEDEV expect the second parameter to be the name of a device file where 
the device is located, such as /dev/tty. For the DGL to Starbase handlers only (D0056, B0056, 
L0056, P0056, V0056) the second parameter takes the form 

filename device_driver. 

The following table shows several path names and their associated lengths. 
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PATH NAME 


LENGTH 


Most DGL handlers: /dev/tty 8 

D0056: /dev/tty hp98700 16 

B0056: /dev/hil2 hp-hil 16 

Figure I.l. The Second Parameter 

The first parameter to the ZBINT or ZDINT call is the length of the entire second parameter. 
The length of the second parameter is the number of characters in the device file name, plus one 
for the space between the device file name and the Starbase device identifier, plus the number 
of characters in the Starbase device driver name. There must be exactly one space in the string 
or an error may be reported. 

There is also a way to default the Starbase device driver name so that existing code which only 
specifies the path name will continue to run. If you wish to use the default name, the ZxINT 
call should specify only the device file name, the same way that all other device handlers require 
the name to be specified. The default Starbase driver name is specified by linking additional 
libraries. The library names have the form 

d.<starbase id> 

where <starbase id> is a shortened form of the Starbase GOPEN driver type parameter, usually 
shortened by removing the leading hp. 

Some library names are: 

d.98700 corresponds to hp98700 

d.98710 corresponds to hp98710 

d.98760 corresponds to hp98760 

d.262x corresponds to hp262x 

d.2623 corresponds to hp2623 

d.2627 corresponds to hp2627 

d.hpgl corresponds to hpgl 

d.hil corresponds to hp-hil 

d.kbd corresponds to keyboard 

A complete list of libraries may be found by looking in the HP-UX directory /lib. 

One of these default name libraries should be specified after each Starbase DGL handler in the 
link command. The default name may always be replaced by an explicit name specified in the 
ZxINT call. 

The Starbase Device Identifiers and the device driver names are defined in the Starbase docu¬ 
mentation. 

To link a DGL program which uses a Starbase DGL handler, you must also include the proper 
Starbase graphics drivers and the Starbase library files. If you wish to specify a default Starbase 
driver name, the default name libraries must also be linked in. 
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As an example, assume a program which uses a Starbase display and button, and standard DGL 
locator and alpha devices. The button device will default to a hp-hil device and the display will 
default to a hp98700 device. The compile command could be: 


fc -X -o demo demo.f -lAOOOO -1L0004 \ 
-1B0056 -Id.hil -Iddhil \ 
-1D0056 -Id.98700 -ldd98700 \ 
-IDIDD \ 

-Isbl -lsb2 


<<< Alpha, Locator 
<« Button, default, starbase 
«< Display, default, starbase 
<« Device Independent 
<<< Starbase Device Independent 


Note the standard DGL rules are followed: link all devices except the display, then link the 
display, then link DIDD. With each Starbase DGL handler an optional default name may be 
specified. The same default name may be specified for more than one Starbase DGL handler. 
Each handler also requires that the Starbase driver be loaded. Each Starbase driver must be 
loaded once only. (If both the button and the locator are hp-hil devices, specify -Iddhil only 
once; you may specify d.hil several times however.) Finally, link the device independent Starbase 
libraries. 


Color Table Size Change 

Every graphic display device has a default color table, which is loaded whenever the corre¬ 
sponding device handler is loaded. The default tables of specific devices are given in the Device 
Handlers Manual. 

For some devices, the number of colors in the default table can be increased at link time. Consult 
the Device Handlers Manual for a specific device to determine if its color table can be resized. 
This number must never be made greater than 32767 (the system limit), or fewer than the 
default size for the device. 

If the number of entries in the color table is increased, each new entry has the same default 
parameters as entry 1. If nothing more is done, the effect of referencing any entry greater than 
the default size will be the same with the modified table as with the default table. If the new 
entries are to permit the display of new colors, their contents must be redefined within the 
program using ZDCOL. 

To change the size of the color table: 

1. Make a copy of the source file: /usr/lib/graphics/fortran/zlctb.f. 

2. Modify the copy using the instructions documented in the source code. 

3. Compile the source module with fc -c zlctb.f. 

4. Link the new color table in with the DGL program. Examples are shown for the various 
types of main programs. 

• FORTRAN program: 

fc program.f zlctb.o -1B0004 -1L0006 -1D0031 -IDIDD 

• Pascal program: 

pc program.p zlctb.o -1B0004 -1L0006 -1D0031 -IDIDD -1F77 -1177 
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• C program: 

cc program.c zlctb.o -1B0004 -1L0006 -1D0031 -IDIDD -1F77 -1177 -Im 


Polygon Intercept Buffer Size Change 

Most device-independent polygon-filling routines compute all the locations where a given fill line 
intercepts the edge of the polygon set. If a polygon set edge has n segments, up to n ;interceptes 
can be generated for the worst case of a concave or self-intersecting polygon set. DGL stores the 
intercept locations in an intercept buffer. If the number of intercepts overflows the buffer, the 
fill line is not drawn. In this case, singel fill lines or portions of the polygon set will not be filled. 
The intercept buffer has a 100 point default capacity, whicfhcan be changed only by modifying 
the source code. 

To change the size of the plygon intecept buffer: 

1. Make a copy of the source file /usr/lib/graphics/f ortran/tllint .f. 

2. Modify the copy using the instructrion documented in the source code. 

3. Compile the source module using fc -c tllint.f. 


97084-90001, new page: 5/85 
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U. Link the new polygon intercept buffer in with the DGL program. Examples 
are shown for the various types of main prograuns. 

FORTRAN program: 

fc program.f tlint.o -IBOOOU -ILOOO 6 -IDOO 3 I -IDIDD 
Pascal program: 

pc program.p tlint.o -IBOOOU -ILOOO 6 -IDOO 3 I -IDIDD -1F77 -1177 
C program; 

cc program.c tlint.o -IBOOOU -ILOOO 6 -IDOO 3 I -IDIDD -1F77 -1177 -Im 


PERFORMANCE 


Although several things can influence the performance of DGL application 
programs, the one the programmer can most easily control is the timing mode 
used to send graphics commands to a device. The default timing mode, system 
buffering, is the most efficient method because it buffers all graphics com- 
majids before they are transmitted; this minimizes the number of data trains- 
fers. Therefore, system buffering reduces the ajnount of time spent in the 
operating system as well as time spent performing input and output. When 
operating in immediate visibility mode, a data transfer occurs for each 
graphics command. 

In system buffering mode, a program can update the image whenever necessary 
by performing an input operation or by calling ZMCUR. Both operations 
flush the DGL buffer and therefore update the image. 


OUTSPOOLING GRAPHICS 


DGL allows the user to outspool graphics commands but does not do the spool¬ 
ing itself. Some devices may not support spooling. 

Outspooling is enabled by setting bit 0 of the control word in the ZDINT 
call. If bit 0 is not set, DGL checks to be sure the type of device the I/O 
imit descriptor points to is correct. If bit 0 is set (i.e., spooling is 
enabled), DGL does not check the type. 

If the alphanumeric device and the graphics display device are identical, 
alphanumeric data and graphics data can be spooled simultaneously; but it is 
necessary to enable the graphics display before enabling the alphanumeric 
display. 
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DGL output can be outspooled to a disc file which cam later be sent to the 
graphics/alphanumeric device. This is useful when identical copies of a 
picture are needed. 

Once created, the file can be sent only to a physical device which is the 
same type supported by the device handler linked with the application 
prograun. For example, if a file was created using am HP 98/20 device hand¬ 
ler, the file can only be sent to am HP 98/20 plotter. 
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KEYBOARD INPUT 


Special Keys 


When using ZKYBD the operator enters the desired text and terminates the 
operation by entering a carriage return. Some keys have a special meaning 
when entered by the operator and are not returned to the application program 
as shown below. 

Key Function 


BACKSPACE Deletes the last character typed. The alphanumeric cursor 

moves back one character and overwrites the character with 
a space. 

LINE FEED A line feed terminates the keyboard operation, the same as 

a carriage return. 


CONTROL-D 


Deletes the last character typed and terminates keyboard 
operation. 


Type-Ahead 


When using the tty (software) terminal interface, HP-UX allows the user to 
type characters at any time, even during output. During the ZDINT call, if 
the spooling bit is not set, atny characters that have been typed ahead are 
cleared to allow DGL to identify the device. At any other time the user may 
type aiiead responses that DGL expects to get from the device. 

Anything that is typed ahead will be treated by DGL as if it had come 
directly from the device. Therefore, the content and order must be exactly 
as expected from the device or incorrect results may occur. For example, 
before requesting locator input from the HP 2623» if the user types in a 
point as ’.23»*45’ an invalid locator point is returned since that is not 
the format for a point that DGL expects from the device. 
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OUTSIDE-WORLD SIGNALS 


Through DGL, the user may end a graphics application program with any of the 
following signals: 

Hang up - signal #1 
Interrupt - signal #2 
Quit - signal #3 

Software termination - signal #15 

DGL uses these signals only if they are set to the system default action 
(which is terraination). ZBEGN checks to see whether or not the user has 
changed the action. If the action has not been changed, DGL responds to a 
signal by attempting to restore devices to their normal state and terminat¬ 
ing graphics (using ZEND) and the program. 

DGL can only detect changes to a signal^s action if the user program makes 
the change before calling ZBEGN. If the program has changed the action, DGL 
takes no action. If desired, the program can terminate just graphics (using 
ZEND) after it intercepts the signal and then continue to operate. For more 
information on the use of signals, refer to the appropriate HP-UX manual. 

CAUTION: For devices that store commands in internal buffers (such as the HP 
758OB Drafting Plotter), graphics output may continue for a while after the 
signal has been sent. 
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Part II 

System-Dependent Calls 


INTRODUCTION 


The calls described in this supplement contain system-dependent information. 
These descriptions, together with the (system-independent) call descriptions 
in the DGL Reference Manual provide complete documentation for DGL 
subroutines. 

The format of the following pages is the saime as the format in the Reference 
Manual. You may insert these call descriptions in the DGL Reference Manual 
(in alphabetical order) or use this system-specific manual as it is. 
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ZAINT 


ZAINT 


PURPOSE: To enable the alphanumeric device. 

CALLING SEQUENCE: CALL ZAINT ( lODLEN, lODES, lERR ) 


lODLEN [ INTEGER; Input ] 

The number of characters in the device name stored in 
IODES. 

lODES [ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 

lERR [ INTEGER; Output ] 

A return code indicating whether the alphanumeric 
device was successfully enabled. 

lERR = 0 Alphanumeric device successfully enabled. 

= 1 The alphainumeric device is not supported on this work 
station. This occurs when the user loads a dummy 
device handler instead of the alphanumeric device hand¬ 
ler. Call ignored. 

= 2 The requested device is not available. This can occur 
for the following reasons: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O unit descriptor is 
not the same as the one specified in the device 
handler, 

o The lODLEN specified is less than one or greater 
than 132. 

Call ignored. 

ZAINT enables the alphanumeric device for output (ZAEND disables it). Call 
ZAINT before attempting to output alphanumeric data using ZALPH. ZAINT as¬ 
sociates the logical device with a physical device; it implicitly makes the 
picture current and then initializes the device. The device name is then 
set to the name of the physical device and the device status is set to 1 
(enabled). 

If aji alphainumeric device is currently enabled a call to ZAINT terminates 
the enabled device (using ZAEND) and then continues. 
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Alphanumeric data can be outspooled to the same I/O unit descriptor as that 
of a currently enabled graphics display device. To outspool to the al- 
phainumeric device it must be enabled after the graphics display device has 
been enabled. 

The alphanumeric device should be disabled before ending the application 
program. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2) Alphantuneric device not supported on this work station. 

ACTION: lERR set to 1 and rest of call ignored. 

3) Alphanumeric device already enabled. 

ACTION: Currently enabled device is terminated through an implicit call 
to ZAEND, and call continues. 

U) Requested device not at the specified I/O unit descriptor. 

ACTION: lERR set to 2 and rest of call ignored. 
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ZBINT 


ZBINT 


PURPOSE: To enable the logical button device. 

CALLING SEQUENCE: CALL ZBINT ( lODLEN, lODES, lERR ) 

lODLEN [ INTEGER; Input ] 

The number of characters in the device name stored in 
lODES. 

lODES [ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 

lERR [ INTEGER; Output ] 

A return code indicating whether the button device was 
successfully enabled. 

lERR = 0 Button device successfully enabled. 

= 1 The button device is not supported on this work sta¬ 
tion. This occurs when the user loads a dummy device 
handler instead of the button device handler. Call 
ignored. 

= 2 The requested device is not available. TTiis can occur 
for the following reasons: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O unit descriptor is 
not the same as the one specified in the device 
handler. 

o The lODLEN specified is less than one or greater 
than 132. 

Call ignored. 

= 3 The specified physical device is an outspooled graphics 
display device. Call ignored. 
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ZBINT enables a logical button device for input (ZBEND disables it). ZBINT 
associates the logical device with a physical device; it implicitly makes 
the picture current aind then initializes the device. The device name is 
then set to the name of the physical device and its status is set to 1 
(enabled). 

ZBUTN is used to perform the button input once the button device is enabled. 
If a button device is currently enabled^ ZBINT terminates the enabled device 
(using ZBEND) and then continues. 

Note that a logical device cannot be enabled for input if output is being 
spooled from the physical device (see ZDINT). 

Disable the button device before ending the application program. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2) Button device is not supported on this work station. 

ACTION: lERR is set to 1 and the rest of the call is ignored. 

3) Button device already enabled. 

ACTION: Currently enabled button device is terminated aind the call 
continues. 

k) Attempt to enable input on the same physical device as an outspooled 
graphics display device. 

ACTION: lERR set to 3 and rest of call ignored. 

5) The requested device is not at the I/O unit descriptor specified. 

ACTION: lERR set to 2 and rest of call ignored. 
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ZDINT 


PURPOSE: To enable a graphics display device. 


CALLING SEQUENCE: CALL ZDINT ( lODLEN, lODES, CONTRL, lERR ) 


lODLEN [ INTEGER; Input ] 

The number of characters in the device name stored in 
lODES. 

lODES [ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 

CONTRL [ INTEGER; Input ] 

Controls the characteristics of the graphics display 
device. Bits should be set according to the following 
map (all unused bits set to 0). 


I D| D| D| D| Dl D| D| Dl X| X| 0| 0| 0| 0| 0| X| 


15 lU 13 12 11 10 9 8 7 6 5 ^ 3 2 1 0 

BIT 0 = 0- Graphics data cannot be outspooled to the 
I/O unit descriptor. 

= 1 - Graphics data can be outspooled to the I/O 
unit descriptor. DGL does not do the 
spooling; it only ensures that nothing is 
read from the device so the system can out- 
spool the data. 

BITS 1-5 “ Currently unused. Should be set to 0. 

BIT 6=0- When ZNEWF is called, the graphics display 
is made current and then the display is 
cleared. 

= 1 - When ZNEWF is called, the graphics display 
is made current but the instruction to 
clear the graphics display is stored in the 
DGL buffer; the instruction is then ex¬ 
ecuted the next time the buffer is sent. 


HP-UX DGL Supplement 
II-6 





ZDINT 


lERR 


When the buffer is sent, the display will 
be cleared and whatever calls to DGL were 
put into the buffer after the ZNEWF call 
will take effect on the graphics display. 
Note that if immediate visibility is used, 
the action is the same as if bit 6 were 0 
since the buffer is sent after every DGL 
call. 

BIT 7=0- ZDINT clears the graphics display. This 
action is not affected by the value of bit 
6 (i.e. even if buffered new-frame-action 
is requested, ZDINT clears the screen 
immediately). 

= 1 - The graphics display is not cleared during 
initialization. If the physical background 
color in effect is different from the ini¬ 
tial value of color 0 (DGL’s background 
color), the physical background color will 
be updated when the buffer is flushed or 
when ZNEWF is called, depending on the 
device. Also, if the device has retroac¬ 
tive color definition and the color table 
has been redefined, the colors of the image 
may change because DGL initializes the 
color table to default values. 


BITS 8-15 - D = device-dependent bit. Set to 0 if not 
used. 

[ INTEGER; Output ] 

A return code indicating whether the graphics display 
device was successfully initialized. 

lERR = 0 The graphics device was successfully initialized. 

= 1 The graphics device is not supported by the work sta¬ 
tion. This occurs when the user loads a dummy device 
handler instead of the graphics device handler. Call 
ignored. 

= 2 The requested graphics display device is not available. 
Possible reasons are: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O descriptor is not the 
same as the one specified in the device handler, 
o The lODLEN specified is less than one or greater 
than 132. Call ignored. 
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= 3 An input device has previously been assigned to this 
physical device and the spooling option was specified, 
or the device does not support spooling. Call ignored. 

Before the device is initialized the device status is 0, the I/O unit 
descriptor length is 0, and the device name is the default naime. The 
default name is the last four characters of the display library loaded, fol¬ 
lowed by two blanks. For example, for the HP 7^70A Plotter, the required 
library is D0031, and the default name is "0031 When a device is en¬ 

abled the device status is set to 1 (enabled) and I/O unit descriptor of the 
device is connected. If the spooling option is used, the device name 
remains set to the default name; otherwise the device name is set to the 
device being used. See the Device Handlers Manual. 

If the spooling option is not used (that is, bit 0 of CONTRL is set to 0), 
ZDINT checks whether the graphics display device is up. Then, if possible, 
DGL inquires the device name from the device at the I/O unit descriptor. 
Unpredictable results occur if there is no device at the I/O unit descrip¬ 
tor, if the device is not the intended graphics device, if the device is 
turned off or in a local mode, or if the connection between the device and 
the computer is bad. 

If an input device is currently enabled on the same physical device 
specified when ZDINT is called and spooling is requested, ZDINT generates an 
error (lERR =3)* 

Note that some devices cannot be outspooled. See the Device Handlers 
Manual . 

Alphanumeric data can be outspooled to the same I/O unit descriptor as that 
of a currently enabled graphics display device. To do this, enable the al¬ 
phanumeric device after enabling the graphics display device. 

Initialization includes the following operations: 

1. The graphics display surface may be cleared (see BIT 7 of CONTRL). 

2. The starting position is set to a device-dependent location. 

3. The logical display limits are set to the default limits for the 
device. 

U. The aspect ratio of the virtual coordinate system is applied to the 
logical display limits to define the limits of the virtual coor¬ 
dinate system. 

5. All primitive attributes are set to their default values. 

6. The locator echo position is set to its default value. 

7. If the display and the locator are the same physical device, the 
logical locator limits are set to the limits of the view surface. 
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Only one type of graphics display device cam be accessed by a DGL 
application program. A single program, however, cam send output to several 
devices of the same type. For example, after sending graphics output to an 
HP 7U7O, a program could disable it and then reassociate the graphics output 
with amother HP 7^70 by changing the value of the I/O unit descriptor. 

If the graphics display device is currently enabled, a call to ZDINT ter¬ 
minates the enabled device (using ZDEND) and then continues. 

After this call, the starting position should be established with a call to 
a primitive which sets but does not begin at the starting position; such 
calls place the physical pen or beam at a known location on the graphics 
display device. Examples are: ZMOVE, ZPOLY, ZPGDI, ZPGDD, ZIMOV, ZIPLY, 
ZIPGI, and ZIPGD. 

No other program should send data to the I/O unit descriptor while it is in¬ 
itialized for use by DGL. There is no DGL error check for this occurrence 
amd the results are unpredictable. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2) The graphics display device is not supported on the work station. 

ACTION: lERR is set to 1 and the rest of the call is ignored. 

3) A device is already enabled as the graphics display device. 

ACTION: The device is terminated and ZDINT continues. 

U) The outspooling option is specified and an input device is already en¬ 
abled on the specified physical device. 

ACTION: lERR is set to 3 and the rest of the call is ignored. Disable 
the logical input device. 

5) Although the device does not support outspooling, outspooling was 
requested by the CONTRL parameter in ZDINT. 

ACTION: lERR set to 3 and rest of call ignored. 

6) The graphics display device is not at the I/O unit descriptor specified. 
ACTION: lERR is set to 2 and the rest of the call is ignored. 
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ziws 


PURPOSE: To inquire characteristics of the DGL system. 

CALLING SEQUENCE: CALL ZIWS ( OPCODE, SSIZE, ISIZE, RSIZE, SLIST , 

ILIST, RLIST, lERR ) 


OPCODE [ INTEGER; Input ] 

The code specifying which characteristic of the DGL sys¬ 
tem system is being queried. The supported values of 
OPCODE are listed below. 

SSIZE [ INTEGER; Input ] 

Maximum number of characters that are to be returned in 
the array SLIST by the function specified by OPCODE. 

ISIZE [ INTEGER; Input ] 

The number of integer parameters that are returned in the 
array ILIST by the function specified by OPCODE. 

RSIZE [ INTEGER; Input ] 

The number of real parameters that are returned in the 
array RLIST by the function specified by OPCODE. 

SLIST [ INTEGER; Array; Output ] 

An array of characters that represent characteristics of 
the work station specified by the value of OPCODE. SLIST 
must be dimensioned large enough to hold SSIZE 

characters. 

ILIST [ INTEGER; Array; Output ] 

An array of integer values that represent the charac¬ 
teristics of the work station requested by OPCODE. ILIST 
must be dimensioned large enough to hold ISIZE 

characters. 

RLIST [ REAL; Array; Output ] 

An array of real values that represent the characteris¬ 
tics of the work station specified by the value of 
OPCODE. RLIST must be dimensioned large enough to hold 
RSIZE characters. 

lERR [ INTEGER; Output ] 

Return code indicating whether the inquiry was performed. 

lERR = 0 Inquiry successfully performed. 

= 1 OPCODE invalid. Call ignored. 
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= 2 ISIZE not equal to nvunber of integer parameters 
returned by OPCODE. Call ignored. 

= 3 RSIZE not equal to number of real parameters 
returned by OPCODE. Call ignored. 

= k SSIZE not large enough to receive the character 
string requested by OPCODE or SSIZE should be 0 
for the OPCODE. Call ignored. 


The subroutine ZIWS returns current information about the DGL system to the 
application program. The type of information desired is specified by a 
unique value for OPCODE. OPCODE digits have the following meanings: 


Ten thousands digit = 1 if a character string is returned in SLIST. 

= 0 if no string returned. 


Thousajids digit = Number of integer values returned in ILIST. 

Hundreds digit = Number of real values returned in RLIST. 


Supported values of OPCODE and their meanings: 


OPCODE MEANING 

250 Actual cell size for a graphics text character, in world coor¬ 
dinates, as determined by the "smaller best fit" rule. 

RLIST(1) = Character cell width. 

(2) = Character cell height. 

251 Marker size in world coordinates (valid only if a graphics 
display device is enabled). 

RLIST(1) = Marker width. 

(2) = Marker height. 

252 Resolution of graphics display on a CRT in points/mm. 

RLIST(l) = Resolution in X-direction. 

(2) = Resolution in Y-direction. 
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253 Maximum dimensions in mm of display surface of graphics device 

(may be wrong if device not yet enabled). 

RLIST(l) = Maximum size in X-direction. 

(2) = Maximum size in Y-direction. 

25 ^ Aspect ratios. 

RLIST(l) = Aspect ratio of virtual coordinate system. 

(2) = Aspect ratio of logical display limits. 

255 Resolution of locator device in points/mm. 

RLIST(l) = Resolution in X-direction. 

(2) = Resolution in Y-direction 

256 Maximum dimensions of locator device in mm. 

RLIST(l) = Maximum size in X-direction. 

(2) = Maximum size in Y-direction. 

257 Locator echo position in world coordinates. 

RLIST(l) = X-coordinate of position. 

(2) = Y-coordinate of position. 

258 Virtual-coordinate limits. 

RLIST(l) = Maximum X-coordinate. 

(2) = Maximum Y-coordinate. 

259 Starting position in world coordinates. (Undefined after a 
text call, an escape function call, changes to the viewing 
transformations, or the enabling of a graphics device.) 

RLIST(l) = X-coordinate of position. 

(2) = Y-coordinate of position. 

U 50 Window limits in world coordinates. 

RLIST(l) = Minimum X-coodinate of window. 

(2) = Maximum X-coodinate of window. 

(3) = Minimum Y-coodinate of window. 

(k) = Maximum Y-coodinate of window. 

U 5 I Viewport limits in virtual coordinates. 

RLIST(l) = Minimum X-coordinate of viewport. 

(2) = Maximum X-coordinate of viewport. 

(3) = Minimum Y-coordinate of viewport. 

(4) = Maximum Y-coordinate of viewport. 
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1050 Does the graphics display device support hardware clipping? 
ILIST(l) = 0 - No. 

= 1 - Yes, to the view surface boundaries. 

= 2 - Yes, but only to the physical limits of the 
display surface. 

1051 Justification of the view surface within the logical display 
limits. 

ILIST(l) = 0 - View surface is centered within the logic dis¬ 
play limits. 

= 1 - View surface origin is at the lower left comer 
of the logical display limits. 

1052 Can the graphics display device draw using the background 
color? 

ILIST(l) = 0 - No. 

= 1 - Yes. 

1053 Total number of non-dithered colors supported on the graphics 
display. The number returned does not include the background 
color (compare opcodes 1053 > 105 ^> 1075)* 

ILIST(l) = Number of distinct colors supported (color 
palette)• 

I 05 U N\imber of non-dithered distinct colors which can appear on the 
graphics display at one time. The number returned does not 
include the background color (compare opcodes 1053 > 105 ^> 

1075 .) 

ILIST(l) = Number of distinct colors which can appear on the 
display at one time (color gamut). 

1055 Number of types of highlighting supported on the graphics 
device. 

ILIST(l) = Number of highlights. 

1056 Number of linestyles supported on the graphics device. 

ILIST(l) = Number of hardware linestyles. 

1057 Number of linewidths supported on the graphics device. 

ILIST(l) = Number of linewidths. 
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1058 Number of hardware character sizes supported on the graphics 
device. 

ILIST(l) = Number of character sizes. If ILIST(l) = -1, the 
graphics device supports continuously varying 
character sizes. 

1059 Number of markers supported on the graphics device. 

ILIST(l) = Number of markers. 

1060 Color index for line primitives. 

ILIST(l) = Color index value. 

1061 Highlighting attribute. 

ILIST(l) = Highlight value. 

1062 Linestyle index for all primitives excluding polygon interior 
fill. 

ILIST(l) = Linestyle index value. 

1063 Linewidth attribute. 

ILIST(l) = Linewidth value. 

IO 6 U Timing mode for displaying graphics primitives. 

ILIST(l) = 0 - Display is immediate. 

= 1 - Display is delayed because DGL commands are 
buffered. 

1065 Number of entries in the polygon style table. If this number 
is 0, the table cainnot be chainged because dummy polygon 
routines were loaded. 

ILIST(l) = 0 - Polygon routines not available. 

> 0 - Number of styles in the table. 

1066 Color index for polygon interiors. 

ILIST(l) = Color index value. 

1067 Polygon style index. 

ILIST(l) = Value of polygon style index. 
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1068 Nvimber of polygon vertices supported by the graphics device. 

ILIST(l) =0 - No hardware support. 

= n (0 < n < 32767 ) “ Number of vertices. 

= 32767 “ No hardware limit on nvimber of 

vertices. 

1069 Does the graphics device support immediate, retroactive change 
of polygon style for polygons already displayed? 

ILIST(l) = 0 - No. 

=1 - Yes. 

1070 Does the graphics device support hardware generation of 
polygons using ZPGDD? 

ILIST(l) = 0 - No. Use ZPGDI instead. 

=1 - Yes. 

1071 Does the graphics device support immediate, retroactive color 
change for primitives already displayed? 

ILIST(l) = 0 - No. 

= 1 - Yes. 

1072 Can the backgrovind color of the graphics device be changed? 

ILIST(l) = 0 - No. 

=1 - Yes. 

1073 Can entries in the color table of the graphics device be 
redefined using ZDCOL? 

ILIST(l) = 0 - No. 

=1 - Yes. 

107*+ Color model in use. 

ILIST(l) = 1 - RGB. 

= 2 - HSL. 

1075 Number of entries in the color table. The number returned 
does not include the background color (compare opcodes 1053 » 
IO 5 U, 1075 ). 

ILIST(l) = 0 - Color table cannot be changed. 

ILIST(l) > 0 - Number of entries in the table. 

1076 Linestyle index for polygon interior fill. 

ILIST(l) = Value of polygon interior linestyle index. 

2050 For internal use only. 
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11050 Graphics display device association. 



SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

11051 

ILIST(l) = Number of characters in the device 
descriptor (132 character maiximum). 

Keyboard device association. 

I/O 

unit 


SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

11052 

ILIST(l) = Number of characters in the device 
descriptor (132 character maximum). 

Locator device association. 

I/O 

unit 


SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

11053 

ILIST(l) = Number of characters in the device 
descriptor (132 character maximum). 

Button device association. 

I/O 

unit 


SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

1105U 

ILIST(l) = Number of characters in the device 
descriptor (132 character maximum). 

Alphanumeric device association. 

I/O 

\init 


SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

11055 

ILIST(l) = Number of characters in the device 
descriptor (132 character maximum). 

Valuator device association. 

I/O 

\mit 


SLIST(l) = Character string containing device 
descriptor. 

I/O 

unit 

12050 

ILIST(l) = Number of characters in the device 
descriptor (132 character maximum). 

Graphics display device information. 

I/O 

unit 


SLIST(l) = Character string containing device name, blank 
filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status 

= -1 There is no graphics display device loaded. 

= 0 Graphics display device is not enabled. 

= 1 Graphics display device is enabled. 
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12051 Keyboard device information. 

SLIST(l) = Character string containing device name, blank 
filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status 

" “1 Tliere is no keyboard device loaded. 

= 0 Keyboard device is not enabled. 

= 1 Keyboard device is enabled. 

13052 Locator device information. 

SLIST(l) = Character string containing device name, 
blank-filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status. 

= -1 There is no locator loaded. 

= 0 Locator device is not enabled. 

= 1 Locator device is enabled. 

ILIST( 3 ) = Number of buttons on the locator device ( 0 if 

there is no locator device loaded). 

13053 Button device information. 

SLIST(l) = Character string containing device name, 

blank-filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status. 

= "I There is no button loaded. 

= 0 Button device is not enabled. 

= 1 Button device is enabled. 

ILIST( 3 ) = Number of buttons on the button device ( 0 if there 
is no button device loaded). 

lU 05 ^ Alphanximeric device information. 

SLIST(l) = Character string containing device name, 

blank-filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status. 

= -1 There is no alphanumeric device loaded. 

= 0 Device is not enabled. 

= 1 Device is enabled. 

ILIST( 3 ) = Maximum niimber of lines displayable at once. 
ILIST(U) = Maximum number of characters per line. -1 if un- 
derminable (e.g. 1 ineprinter). 
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II4O55 Valuator device information. 

SLIST{ 1 ) = Character string containing device name, 
blank-filled. 

ILIST(l) = Number of characters in the device name (always 6 ). 
ILIST( 2 ) = Status. 

= -1 There is no valuator loaded. 

= 0 Device is not enabled. 

= 1 Device is enabled. 

ILIST( 3 ) = Number of buttons on the valuator device ( 0 if 
there is no valuator device loaded). 

ILIST(U) = Number of sub-valuators supported. 

ERROR CONDITIONS: 

1 ) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2 ) Invalid OPCODE specified. 

ACTION: lERR is set to 1 and the rest of the call is ignored. 

3 ) ISIZE is not equal to the number of integer values to be returned. 

ACTION: lERR is set to 2 and the rest of the call is ignored. 

U) RSIZE is not equal to the number of real values to be returned. 

ACTION: lERR is set to 3 and the rest of the call is ignored. 

5 ) SSIZE is not large enough to receive the character string requested or 
SEIZE should be 0 for the OPCODE. 

ACTION: lERR is set to U and the rest of the call is ignored. 
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ZKINT 


PURPOSE: To enable the keyboard device. 

CALLING SEQUENCE: CALL ZKINT ( lODLEN, lODES , lERR ) 


lODLEN [ INTEGER; Input ] 

The number of characters in the device name stored in 
lODES. 

lODES [ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 

lERR [ INTEGER; Output ] 

A return code indicating whether the keyboard device 
was successfully enabled. 

lERR = 0 The keyboard was successfully enabled. 

= 1 The keyboard device is not supported on this work sta¬ 
tion. This occurs when the user loads a dummy device 
handler instead of the keyboard device handler. Call 
ignored. 

= 2 The requested device is not at the specified I/O unit 
descriptor. This can occur for the following reasons: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O unit descriptor is 
not the same as the one specified in the device 
handler. 

o The lODLEN specified is less than one or greater 
than 132. 

Call ignored. 

= 3 An input device has previously been assigned to this 
physical device and the spooling option was specified, 
or the device does not support spooling. 

Call ignored. 

ZKINT enables the logical keyboard device for input (disable with ZKEND) by 
associating the logical with the physical keyboard device and initializing 
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the device. (ZKINT implicitly makes the picture current before attempting 
to initialize the device.) The device name is set to the name of the 
physical device and the device status is set to 1 (enabled). 

If the keyboard is currently enabled, ZKINT terminates the enabled device 
(using ZKEND) and continues. 

Note that if a physical device is being used as an outspooled graphics dis¬ 
play device, a logical input device cannot be enabled on it. 

Call ZKYBD to return a string from the enabled keyboard. 


ERROR CONDITIONS: 

1 ) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2 ) Keyboard device not supported on this work station. 

ACTION: lERR is set to 1 and the rest of the call is ignored. 

3 ) Keyboard device already enabled. 

ACTION: Enabled keyboard device is terminated and the call continues. 

4 ) Attempt to enable input on the same physical device as an outspooled 
graphics display device. 

ACTION: lERR set to 3 3 ind rest of call ignored. 

5 ) The specified I/O unit descriptor does not support a logical keyboard 
device. 

ACTION: lERR set to 2 and rest of call ignored. 
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PURPOSE: To enable 

CALLING SEQUENCE: 

lODLEN 

I ODES 

lERR 

lERR = 0 
= 1 

= 2 


ZLINT 


the locator device for input. 


CALL ZLINT ( lODLEN, lODES, lERR ) 


[ INTEGER; Input ] 

The number of characters in the device name stored in 
lODES. 

[ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 


[ INTEGER; Output ] 

A return code indicating whether the locator device was 
successfully enabled. 

Locator device was successfully enabled. 

Locator device is not supported on this work station. 
This occurs when the user loads a dummy device handler 
instead of the locator device handler. Call ignored. 

The requested device is not at the I/O unit descriptor. 
This can occur for the following reasons: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O unit descriptor is 
not the same as the one specified in the device 
handler. 

o The lODLEN specified is less than one or greater 
than 132 . 

Call ignored. 

The specified physical device is an outspooled graphics 
display device. Call ignored. 
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ZLINT enables the logical locator device for input (ZLEND disables it) by 
associating the logical locator device with a physical device and initializ¬ 
ing the device. (ZLINT implicitly makes the picture current before in¬ 
itializing the device.) The device name is set to the name of the physical 
device and the device status is set to 1 (enabled). The locator echo posi¬ 
tion is set to the default value (see ZLOCP). 

If the specified I/O unit descriptor is not the same as that of an enabled 
display device, then the logical locator limits will be set to the default 
values for the particular locator used. If the I/O unit descriptor 
specified is the same as that of an enabled display device, then the logical 
locator limits are set to the current view surface limits. If the locator 
is currently enabled, ZLINT terminates the enabled device (using ZLEND) and 
continues. Be sure to disable the locator device before terminating the ap¬ 
plication program. 

A logical input device cannot be enabled on the same physical device as an 
outspooled graphics display device (see ZDINT). 


ERROR CONDITIONS: 

1 ) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2 ) Locator device is not supported on this work station. 

ACTION: lERR set to 1 and rest of call ignored. 

3 ) Locator device already enabled. 

ACTION: Enabled locator device is terminated and call continues. 

U) Attempt to enable input on an outspooled graphics display device. 

ACTION: lERR set to 3 and rest of call ignored. 

5 ) The locator device requested is not at the I/O unit descriptor 
specified. 

ACTION: lERR set to 2 and rest of call ignored. 
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PURPOSE: To enable 

CALLING SEQUENCE: 

lODLEN 

lODES 

lERR 

lERR = 0 
= 1 

= 2 


ZVINT 


the logical valuator device. 


CALL ZVINT ( lODLEN, lODES, lERR ) 


[ INTEGER; Input ] 

The number of characters in the device name stored in 
lODES. 

[ INTEGER; Array; Input ] 

The name of the I/O unit descriptor, expressed as a 
character string. 

[ INTEGER; Output ] 

A return code indicating whether the valuator device 
was successfully enabled. 

The valuator device was successfully enabled. 

The valuator device is not supported on this work sta¬ 
tion. This occurs when the user loads a dxammy device 
handler instead of the valuator device handler. Call 
ignored. 

The requested device is not at the I/O unit descriptor. 
This can occur for the following reasons: 

o The incorrect I/O unit descriptor was specified, 
o The specified device is down. 

o The physical device at the I/O unit descriptor is 
not the same as the one specified in the device 
handler. 

o The lODLEN specified is less than one or greater 
than 132. 

Call ignored. 

The specified physical device is an outspooled graphics 
display device. Call ignored. 
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ZVINT enables the logical valuator device for input (ZVEND disables it) by 
associating the logical valuator device with a physical device and in¬ 
itializing the device. (ZVINT implicitly makes the picture current before 
initializing the device.) The device name is set to the name of the physi¬ 
cal device and the device status is set to 1 (enabled). 

The valuator device should be enabled before it samples or requests data. 
If the valuator is currently enabled, ZVINT terminates the enabled device 
(using ZVEND) and continues. 

A logical input device cannot be enabled on the saime physical device as an 
outspooled graphics display device (see ZDINT). 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize the DGL system. 

2) The valuator device is not supported on this work station. 

ACTION: lERR set to 1 and rest of call ignored. 

3) The valuator device already enabled. 

ACTION: Enabled valuator device is terminated and call continues. 

k) Attempt to enable input on am outspooled graphics display device. 

ACTION: lERR set to 3 and rest of call ignored. 

5) The valuator device requested is not at the I/O unit descriptor 
specified. 

ACTION: lERR set to 2 and rest of call ignored. 
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Part III 
Integer Interface 


INTRODUCTION 


The integer interface is a set of function calls which allow the user to 
specify primitives using integer coordinates. The integer and real inter¬ 
faces may be used together; portions of the drawing may be done in integer 
and other portions in real. 

The integer interface increases performance but is less accurate thain the 
real interface. The difference between the results of these interfaces will 
be at most two device units. 
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ZIMOV 


PURPOSE: 


To set the starting position to the world coordinate position 
specified. 


CALLING SEQUENCE: ZIMOV ( IX, lY ) 

IX [ INTEGER; Input ] 

X-coordinate of the new starting position in integer 
world coordinates. 

lY [ INTEGER; Input ] 

Y-coordinate of the new starting position in integer 
world coordinates. 


ZIMOV specifies a new starting position. It does this by setting the value 
of the starting position to the world coordinate system point specified by 
( IX,lY ). This point will then be the starting position of the next output 
primitive. 

Since the DGL system does not perform software clipping, setting the start¬ 
ing position to a point outside of the current view surface limits will 
produce device-dependent results. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The logical graphics display is not currently enabled. 

ACTION: Call ignored. 
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ZIDRW 


PURPOSE: To draw a line from the starting position to the world coordinate 
position specified. 


CALLING SEQUENCE: ZIDRW ( IX» lY ) 


IX [ INTEGER; Input ] 

Ending X-coordinate of the line to be drawn* in integer 
world coordinates. 

lY [ INTEGER; Input ] 

Ending Y-coordinate of the line to be drawn, in integer 
world coordinates. 

A line is drawn from the starting position to the world coordinate specified 
by (IX,lY). The starting position is updated to (IX,lY) at the completion 
of this call. 

The DGL system does not perform any software clipping on output primitives. 
If either the starting position or the point (IX,lY) is outside of the cur¬ 
rent view surface, then the resulting picture may not be well defined be¬ 
cause each device handles out-of-rauige data in a different manner. 

Drawing to the starting position generates the shortest line possible. 
Depending on the nature of the linestyle, nothing may appear on the graphics 
display surface. See ZLSTL for a complete description of how linestyle af¬ 
fects a particular point or vector. 

The primitive attributes of linestyle, color, highlighting and linewidth ap¬ 
ply to lines drawn using ZIDRW. However, the lines will appear with these 
attributes only if the graphics device is capable of applying them to lines. 
Check the Device Handlevs Mantuzl for the exact capabilities of the display 
device used to determine the effect of all primitive attributes. 

ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) The graphics display is not enabled. 

ACTION: Call ignored. 
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ZIPLY 


PURPOSE: To draw a sequence of lines beginning at a specified point. 


CALLING SEQUENCE: ZIPLY ( NPTS, IXVEC, lYVEC ) 


NPTS [ INTEGER; Input ] 

Number of points in IXVEC, lYVEC. 

IXVEC [ INTEGER ARRAY; Input ] 

X-coordinates of the polyline points in integer world 
coordinates. 

lYVEC [ INTEGER ARRAY; Input ] 

Y-coordinates of the polyline points in integer world 
coordinates. 


The subroutine ZIPLY provides the capability to draw a series of connected 
lines starting at a specified point. A complete object czin be drawn by 
making one call to this subroutine. This call first sets the starting posi¬ 
tion to be the first elements in the IXVEC,lYVEC arrays. The line sequence 
begins at this point and is drawn to the second element in each array, then 
to the third and continues until NPTS-1 lines are drawn. 

This call is equivalent to the following sequence of calls: 

CALL ZIMOV (IXVEC(1),IYVEC(1)) 

CALL ZIDRW (IXVEC(2),IYVEC(2)) 

CALL ZIDRW (IXVEcb)»IYVEC(3)) 

CALL ZIDRW (IXVEC(NPTS),IYVEC(NPTS)) 

The DGL system does not perform software clipping on output primitives. If 
any of the points specified in IXVEC and lYVEC are outside of the current 
view surface limits, the resulting image will be device dependent. 

The starting position is set to (IXVEC(NPTS), lYVEC(NPTS)) at the completion 
of this call. 
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If NPTS is set to 1» ZIPLY generates a move to the world coordinate point 
(IXVEC(1),IYVEC(1)). 

It is the application program’s responsibility to insure that IXVEC, and 
lYVEC are dimensioned to at least NPTS amd that at least NPTS values are 
contained in each array. 

Depending on the nature of the current linestyle, nothing may appear on the 
graphics display. See ZLSTL for a complete description of how linestyle af¬ 
fects a particular point or vector. 

The primitive attributes of color, highlighting, linestyle, and linewidth 
apply to polylines. However, the polyline will appear with these attributes 
only if the graphics device is capable of applying them to polylines. Check 
the Device Handlers Manual for the exact capabilities of the display device 
used to determine the effect of all primitive attributes. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. A call to ZBEGN must be made to initialize the 
DGL system. 

2) Graphics display is not enabled. 

ACTION: Call ignored. 

3) NPTS <= 0 (Possibly NPTS is a real number.) 

ACTION: Call ignored. 
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ZIPGD 


PURPOSE: To draw a device-dependent polygon. 

CALLING SEQUENCE: ZIPGD ( NPTS, IXVEC, lYVEC, OPCODE ) 


NPTS [ INTEGER; Input ] 

Number of points in IXVEC, lYVEC. 

IXVEC [ INTEGER ARRAY; Input ] 

X-coordinates of the polygon. 

lYVEC [ INTEGER ARRAY; Input ] 

Y-coordinates of the polygon. 

OPCODE [ INTEGER ARRAY; Input ] 

Polygon opcodes for each vertex. 


ZIPGD draws polygon sets in the current polygon style as accurately as pos¬ 
sible, using the hardware capabilities of the graphics device. ZIPGI should 
be used to request that polygon sets be produced in a device-independent 
manner. Generally, ZIPGD draws polygon sets with greater speed and more 
economical use of memory, and ZIPGI draws them with greater accuracy and 
uniformity. 

Polygon fill capabilities can vary widely between devices. A device may 
have no filling capabilities at all, may be able to perform only solid fill, 
or may be able to fill polygons with different fill densities and at dif¬ 
ferent fill line orientations. Some devices may be able to apply their 
capabilities to single rectaingles only, while some may handle the full range 
of concave and convex polygon sets. ZIPGD tries to match the device 
capabilities to the request. 

ZIPGD limits the number of polygon vertices which the user may specify. For 
devices that do not support hardware filling, up to 500 polygon vertices 
will be accepted for scribing the outline of the polygon interior. ZIPGD 
may be further limited by the device in the number of vertices that can be 
filled. If the device does not support hardware filling, see the Device 
Handlers Manual for ZPGDD to determine how memy vertices will be accepted 
for filling by the hardware. If the limit is exceeded, the polygon will not 
be filled. In the case where the polygon style specifies nondisplay of 
edges, to provide some visible output, ZIPGD will outline the polygon using 
the polygon interior fill attributes. However, only those edge segments 
specified as displayable by OPCODE will be drawn. 
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DGL automatically closes each member polygon with a non-visible edge segment 
if its last vertex does not coincide with its first. To display the closing 
edge segment, the first and last vertices must be coincident and OPCODE for 
the last vertex must equal 1. 

The DGL system does not perform any software clipping on output primitives. 
If any of the points specified in IXVEC and lYVEC are outside of the current 
view surface, then the resulting picture may not be well defined because 
each device handles out of rauige data in a different manner. 

At the completion of this call the starting position is set to the first 
vertex of the last member polygon in the set. 

The attributes of color, polygon interior color, highlighting, linestyle, 
polygon interior linestyle, polygon style and linewidth apply to polygons. 
However, the polygons will appear with these attributes only if the graphics 
device is capable of applying them to polygons. Check the Device Handlers 
Manual for the exact capabilities of the display device used to determine 
the effect of all primitive attributes. 


ERROR CONDITIONS: 

1) The DGL system is not initialized. 

ACTION: Call ignored. Call ZBEGN to initialize DGL. 

2) No graphic display device is enabled. 

ACTION: Call ignored. A call to ZDINT must be made to enable a device. 

3) NPOINT is a non-positive integer. 

ACTION: Call ignored. 

U) More vertices are specified in IXVEC and lYVEC than the current graphic 
display device can handle. 

ACTION: The polygon set is outlined. 

5) OPCODE(1) does not equal 2. 

ACTION: Call ignored. 

6) OPCODE(i) (i >1) does not equal 0, 1, or 2. 

ACTION: Polygon set is drawn but results are unpredictable. 
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ZIPGI 


PURPOSE: To draw a device-independent polygon. 

CALLING SEQUENCE: ZIPGI ( NPTS, IXVEC, lYVEC, OPCODE ) 


NPTS [ INTEGER; Input ] 

Number of points in IXVEC, lYVEC. 

IXVEC [ INTEGER ARRAY; Input ] 

X-coordinates of the polygon. 

lYVEC [ INTEGER ARRAY; Input ] 

Y-coordinates of the polygon. 

OPCODE [ INTEGER ARRAY; Input ] 

Polygon opcodes for each vertex. 


ZIPGI draws polygon sets in a device-independent manner. This is done in 
software unless the device is capable of producing polygon sets in the en¬ 
tire polygon style range described below. ZIPGD draws polygon sets using 
the hardware capabilities of the device. Generally, ZIPGI draws polygon 
sets with greater accuracy and uniformity, and ZIPGD draws them with greater 
speed and more economical use of memory. 

ZIPGI limits the number of polygon vertices which the user may specify (500 
maximum). If the limit is exceeded, the polygon will not be filled. In the 
case where the polygon style specifies nondisplay of edges, to provide some 
visible output, ZIPGI will outline the polygon using the polygon interior 
fill attributes. However, only those edge segments specified as displayable 
by OPCODE will be drawn. 

DGL automatically closes each member polygon with a non-visible edge segment 
if its last vertex does not coincide with its first. To display the closing 
edge segment, the first and last vertices must be coincident and OPCODE for 
last vertex must equal 1. 

The DGL system does not perform any software clipping on output primitives. 
If any of the points specified in IXVEC and lYVEC are outside of the current 
view surface, then the resulting picture may not be well defined because 
each device handles out-of-range data in a different manner. 

At the completion of this call, the starting position is set to the first 
vertex of the last member polygon in the set. 


HP-UX DGL Supplement 
III-8 





HEWLETT 

PACKARD 


Part No. 97084-90001 
El 183 


Printed in U.S.A. 
Second Edition 
November 1983 


